codekingpro/portable-devtools
115k
1<?xml version="1.0" encoding="UTF-8" standalone="no"?>2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>pgbench</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="app-pgbasebackup.html" title="pg_basebackup" /><link rel="next" href="app-pgconfig.html" title="pg_config" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center"><span class="application">pgbench</span></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="app-pgbasebackup.html" title="pg_basebackup">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="reference-client.html" title="PostgreSQL Client Applications">Up</a></td><th width="60%" align="center">PostgreSQL Client Applications</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 16.3 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="app-pgconfig.html" title="pg_config">Next</a></td></tr></table><hr /></div><div class="refentry" id="PGBENCH"><div class="titlepage"></div><a id="id-1.9.4.11.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle"><span class="application">pgbench</span></span></h2><p>pgbench — run a benchmark test on <span class="productname">PostgreSQL</span></p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="cmdsynopsis"><p id="id-1.9.4.11.4.1"><code class="command">pgbench</code> <code class="option">-i</code> [<em class="replaceable"><code>option</code></em>...] [<em class="replaceable"><code>dbname</code></em>]</p></div><div class="cmdsynopsis"><p id="id-1.9.4.11.4.2"><code class="command">pgbench</code> [<em class="replaceable"><code>option</code></em>...] [<em class="replaceable"><code>dbname</code></em>]</p></div></div><div class="refsect1" id="id-1.9.4.11.5"><h2>Description</h2><p>3 <span class="application">pgbench</span> is a simple program for running benchmark4 tests on <span class="productname">PostgreSQL</span>. It runs the same sequence of SQL5 commands over and over, possibly in multiple concurrent database sessions,6 and then calculates the average transaction rate (transactions per second).7 By default, <span class="application">pgbench</span> tests a scenario that is8 loosely based on TPC-B, involving five <code class="command">SELECT</code>,9 <code class="command">UPDATE</code>, and <code class="command">INSERT</code> commands per transaction.10 However, it is easy to test other cases by writing your own transaction11 script files.12 </p><p>13 Typical output from <span class="application">pgbench</span> looks like:14 15</p><pre class="screen">16transaction type: <builtin: TPC-B (sort of)>17scaling factor: 1018query mode: simple19number of clients: 1020number of threads: 121maximum number of tries: 122number of transactions per client: 100023number of transactions actually processed: 10000/1000024number of failed transactions: 0 (0.000%)25latency average = 11.013 ms26latency stddev = 7.351 ms27initial connection time = 45.758 ms28tps = 896.967014 (without initial connection time)29</pre><p>30 31 The first seven lines report some of the most important parameter32 settings.33 The sixth line reports the maximum number of tries for transactions with34 serialization or deadlock errors (see <a class="xref" href="pgbench.html#FAILURES-AND-RETRIES" title="Failures and Serialization/Deadlock Retries">Failures and Serialization/Deadlock Retries</a>35 for more information).36 The eighth line reports the number of transactions completed37 and intended (the latter being just the product of number of clients38 and number of transactions per client); these will be equal unless the run39 failed before completion or some SQL command(s) failed. (In40 <code class="option">-T</code> mode, only the actual number of transactions is printed.)41 The next line reports the number of failed transactions due to42 serialization or deadlock errors (see <a class="xref" href="pgbench.html#FAILURES-AND-RETRIES" title="Failures and Serialization/Deadlock Retries">Failures and Serialization/Deadlock Retries</a>43 for more information).44 The last line reports the number of transactions per second.45 </p><p>46 The default TPC-B-like transaction test requires specific tables to be47 set up beforehand. <span class="application">pgbench</span> should be invoked with48 the <code class="option">-i</code> (initialize) option to create and populate these49 tables. (When you are testing a custom script, you don't need this50 step, but will instead need to do whatever setup your test needs.)51 Initialization looks like:52 53</p><pre class="programlisting">54pgbench -i [<span class="optional"> <em class="replaceable"><code>other-options</code></em> </span>] <em class="replaceable"><code>dbname</code></em>55</pre><p>56 57 where <em class="replaceable"><code>dbname</code></em> is the name of the already-created58 database to test in. (You may also need <code class="option">-h</code>,59 <code class="option">-p</code>, and/or <code class="option">-U</code> options to specify how to60 connect to the database server.)61 </p><div class="caution"><h3 class="title">Caution</h3><p>62 <code class="literal">pgbench -i</code> creates four tables <code class="structname">pgbench_accounts</code>,63 <code class="structname">pgbench_branches</code>, <code class="structname">pgbench_history</code>, and64 <code class="structname">pgbench_tellers</code>,65 destroying any existing tables of these names.66 Be very careful to use another database if you have tables having these67 names!68 </p></div><p>69 At the default <span class="quote">“<span class="quote">scale factor</span>”</span> of 1, the tables initially70 contain this many rows:71</p><pre class="screen">72table # of rows73---------------------------------74pgbench_branches 175pgbench_tellers 1076pgbench_accounts 10000077pgbench_history 078</pre><p>79 You can (and, for most purposes, probably should) increase the number80 of rows by using the <code class="option">-s</code> (scale factor) option. The81 <code class="option">-F</code> (fillfactor) option might also be used at this point.82 </p><p>83 Once you have done the necessary setup, you can run your benchmark84 with a command that doesn't include <code class="option">-i</code>, that is85 86</p><pre class="programlisting">87pgbench [<span class="optional"> <em class="replaceable"><code>options</code></em> </span>] <em class="replaceable"><code>dbname</code></em>88</pre><p>89 90 In nearly all cases, you'll need some options to make a useful test.91 The most important options are <code class="option">-c</code> (number of clients),92 <code class="option">-t</code> (number of transactions), <code class="option">-T</code> (time limit),93 and <code class="option">-f</code> (specify a custom script file).94 See below for a full list.95 </p></div><div class="refsect1" id="id-1.9.4.11.6"><h2>Options</h2><p>96 The following is divided into three subsections. Different options are97 used during database initialization and while running benchmarks, but some98 options are useful in both cases.99 </p><div class="refsect2" id="PGBENCH-INIT-OPTIONS"><h3>Initialization Options</h3><p>100 <span class="application">pgbench</span> accepts the following command-line101 initialization arguments:102 103 </p><div class="variablelist"><dl class="variablelist"><dt id="PGBENCH-OPTION-DBNAME"><span class="term"><em class="replaceable"><code>dbname</code></em></span> <a href="#PGBENCH-OPTION-DBNAME" class="id_link">#</a></dt><dd><p>104 Specifies the name of the database to test in. If this is105 not specified, the environment variable106 <code class="envar">PGDATABASE</code> is used. If that is not set, the107 user name specified for the connection is used.108 </p></dd><dt id="PGBENCH-OPTION-INITIALIZE"><span class="term"><code class="option">-i</code><br /></span><span class="term"><code class="option">--initialize</code></span> <a href="#PGBENCH-OPTION-INITIALIZE" class="id_link">#</a></dt><dd><p>109 Required to invoke initialization mode.110 </p></dd><dt id="PGBENCH-OPTION-INIT-STEPS"><span class="term"><code class="option">-I <em class="replaceable"><code>init_steps</code></em></code><br /></span><span class="term"><code class="option">--init-steps=<em class="replaceable"><code>init_steps</code></em></code></span> <a href="#PGBENCH-OPTION-INIT-STEPS" class="id_link">#</a></dt><dd><p>111 Perform just a selected set of the normal initialization steps.112 <em class="replaceable"><code>init_steps</code></em> specifies the113 initialization steps to be performed, using one character per step.114 Each step is invoked in the specified order.115 The default is <code class="literal">dtgvp</code>.116 The available steps are:117 118 </p><div class="variablelist"><dl class="variablelist"><dt id="PGBENCH-OPTION-INIT-STEPS-D"><span class="term"><code class="literal">d</code> (Drop)</span> <a href="#PGBENCH-OPTION-INIT-STEPS-D" class="id_link">#</a></dt><dd><p>119 Drop any existing <span class="application">pgbench</span> tables.120 </p></dd><dt id="PGBENCH-OPTION-INIT-STEPS-T"><span class="term"><code class="literal">t</code> (create Tables)</span> <a href="#PGBENCH-OPTION-INIT-STEPS-T" class="id_link">#</a></dt><dd><p>121 Create the tables used by the122 standard <span class="application">pgbench</span> scenario, namely123 <code class="structname">pgbench_accounts</code>,124 <code class="structname">pgbench_branches</code>,125 <code class="structname">pgbench_history</code>, and126 <code class="structname">pgbench_tellers</code>.127 </p></dd><dt id="PGBENCH-OPTION-INIT-STEPS-G"><span class="term"><code class="literal">g</code> or <code class="literal">G</code> (Generate data, client-side or server-side)</span> <a href="#PGBENCH-OPTION-INIT-STEPS-G" class="id_link">#</a></dt><dd><p>128 Generate data and load it into the standard tables,129 replacing any data already present.130 </p><p>131 With <code class="literal">g</code> (client-side data generation),132 data is generated in <code class="command">pgbench</code> client and then133 sent to the server. This uses the client/server bandwidth134 extensively through a <code class="command">COPY</code>.135 <code class="command">pgbench</code> uses the FREEZE option with version 14 or later136 of <span class="productname">PostgreSQL</span> to speed up137 subsequent <code class="command">VACUUM</code>, unless partitions are enabled.138 Using <code class="literal">g</code> causes logging to print one message139 every 100,000 rows while generating data for the140 <code class="structname">pgbench_accounts</code> table.141 </p><p>142 With <code class="literal">G</code> (server-side data generation),143 only small queries are sent from the <code class="command">pgbench</code>144 client and then data is actually generated in the server.145 No significant bandwidth is required for this variant, but146 the server will do more work.147 Using <code class="literal">G</code> causes logging not to print any progress148 message while generating data.149 </p><p>150 The default initialization behavior uses client-side data151 generation (equivalent to <code class="literal">g</code>).152 </p></dd><dt id="PGBENCH-OPTION-INIT-STEPS-V"><span class="term"><code class="literal">v</code> (Vacuum)</span> <a href="#PGBENCH-OPTION-INIT-STEPS-V" class="id_link">#</a></dt><dd><p>153 Invoke <code class="command">VACUUM</code> on the standard tables.154 </p></dd><dt id="PGBENCH-OPTION-INIT-STEPS-P"><span class="term"><code class="literal">p</code> (create Primary keys)</span> <a href="#PGBENCH-OPTION-INIT-STEPS-P" class="id_link">#</a></dt><dd><p>155 Create primary key indexes on the standard tables.156 </p></dd><dt id="PGBENCH-OPTION-INIT-STEPS-F"><span class="term"><code class="literal">f</code> (create Foreign keys)</span> <a href="#PGBENCH-OPTION-INIT-STEPS-F" class="id_link">#</a></dt><dd><p>157 Create foreign key constraints between the standard tables.158 (Note that this step is not performed by default.)159 </p></dd></dl></div></dd><dt id="PGBENCH-OPTION-FILLFACTOR"><span class="term"><code class="option">-F</code> <em class="replaceable"><code>fillfactor</code></em><br /></span><span class="term"><code class="option">--fillfactor=</code><em class="replaceable"><code>fillfactor</code></em></span> <a href="#PGBENCH-OPTION-FILLFACTOR" class="id_link">#</a></dt><dd><p>160 Create the <code class="structname">pgbench_accounts</code>,161 <code class="structname">pgbench_tellers</code> and162 <code class="structname">pgbench_branches</code> tables with the given fillfactor.163 Default is 100.164 </p></dd><dt id="PGBENCH-OPTION-NO-VACUUM-INIT"><span class="term"><code class="option">-n</code><br /></span><span class="term"><code class="option">--no-vacuum</code></span> <a href="#PGBENCH-OPTION-NO-VACUUM-INIT" class="id_link">#</a></dt><dd><p>165 Perform no vacuuming during initialization.166 (This option suppresses the <code class="literal">v</code> initialization step,167 even if it was specified in <code class="option">-I</code>.)168 </p></dd><dt id="PGBENCH-OPTION-QUIET"><span class="term"><code class="option">-q</code><br /></span><span class="term"><code class="option">--quiet</code></span> <a href="#PGBENCH-OPTION-QUIET" class="id_link">#</a></dt><dd><p>169 Switch logging to quiet mode, producing only one progress message per 5170 seconds. The default logging prints one message each 100,000 rows, which171 often outputs many lines per second (especially on good hardware).172 </p><p>173 This setting has no effect if <code class="literal">G</code> is specified174 in <code class="option">-I</code>.175 </p></dd><dt id="PGBENCH-OPTION-SCALE-INIT"><span class="term"><code class="option">-s</code> <em class="replaceable"><code>scale_factor</code></em><br /></span><span class="term"><code class="option">--scale=</code><em class="replaceable"><code>scale_factor</code></em></span> <a href="#PGBENCH-OPTION-SCALE-INIT" class="id_link">#</a></dt><dd><p>176 Multiply the number of rows generated by the scale factor.177 For example, <code class="literal">-s 100</code> will create 10,000,000 rows178 in the <code class="structname">pgbench_accounts</code> table. Default is 1.179 When the scale is 20,000 or larger, the columns used to180 hold account identifiers (<code class="structfield">aid</code> columns)181 will switch to using larger integers (<code class="type">bigint</code>),182 in order to be big enough to hold the range of account183 identifiers.184 </p></dd><dt id="PGBENCH-OPTION-FOREIGN-KEYS"><span class="term"><code class="option">--foreign-keys</code></span> <a href="#PGBENCH-OPTION-FOREIGN-KEYS" class="id_link">#</a></dt><dd><p>185 Create foreign key constraints between the standard tables.186 (This option adds the <code class="literal">f</code> step to the initialization187 step sequence, if it is not already present.)188 </p></dd><dt id="PGBENCH-OPTION-INDEX-TABLESPACE"><span class="term"><code class="option">--index-tablespace=<em class="replaceable"><code>index_tablespace</code></em></code></span> <a href="#PGBENCH-OPTION-INDEX-TABLESPACE" class="id_link">#</a></dt><dd><p>189 Create indexes in the specified tablespace, rather than the default190 tablespace.191 </p></dd><dt id="PGBENCH-OPTION-PARTITION-METHOD"><span class="term"><code class="option">--partition-method=<em class="replaceable"><code>NAME</code></em></code></span> <a href="#PGBENCH-OPTION-PARTITION-METHOD" class="id_link">#</a></dt><dd><p>192 Create a partitioned <code class="literal">pgbench_accounts</code> table with193 <em class="replaceable"><code>NAME</code></em> method.194 Expected values are <code class="literal">range</code> or <code class="literal">hash</code>.195 This option requires that <code class="option">--partitions</code> is set to non-zero.196 If unspecified, default is <code class="literal">range</code>.197 </p></dd><dt id="PGBENCH-OPTION-PARTITIONS"><span class="term"><code class="option">--partitions=<em class="replaceable"><code>NUM</code></em></code></span> <a href="#PGBENCH-OPTION-PARTITIONS" class="id_link">#</a></dt><dd><p>198 Create a partitioned <code class="literal">pgbench_accounts</code> table with199 <em class="replaceable"><code>NUM</code></em> partitions of nearly equal size for200 the scaled number of accounts.201 Default is <code class="literal">0</code>, meaning no partitioning.202 </p></dd><dt id="PGBENCH-OPTION-TABLESPACE"><span class="term"><code class="option">--tablespace=<em class="replaceable"><code>tablespace</code></em></code></span> <a href="#PGBENCH-OPTION-TABLESPACE" class="id_link">#</a></dt><dd><p>203 Create tables in the specified tablespace, rather than the default204 tablespace.205 </p></dd><dt id="PGBENCH-OPTION-UNLOGGED-TABLES"><span class="term"><code class="option">--unlogged-tables</code></span> <a href="#PGBENCH-OPTION-UNLOGGED-TABLES" class="id_link">#</a></dt><dd><p>206 Create all tables as unlogged tables, rather than permanent tables.207 </p></dd></dl></div><p>208 </p></div><div class="refsect2" id="PGBENCH-RUN-OPTIONS"><h3>Benchmarking Options</h3><p>209 <span class="application">pgbench</span> accepts the following command-line210 benchmarking arguments:211 212 </p><div class="variablelist"><dl class="variablelist"><dt id="PGBENCH-OPTION-BUILTIN"><span class="term"><code class="option">-b</code> <em class="replaceable"><code>scriptname[@weight]</code></em><br /></span><span class="term"><code class="option">--builtin</code>=<em class="replaceable"><code>scriptname[@weight]</code></em></span> <a href="#PGBENCH-OPTION-BUILTIN" class="id_link">#</a></dt><dd><p>213 Add the specified built-in script to the list of scripts to be executed.214 Available built-in scripts are: <code class="literal">tpcb-like</code>,215 <code class="literal">simple-update</code> and <code class="literal">select-only</code>.216 Unambiguous prefixes of built-in names are accepted.217 With the special name <code class="literal">list</code>, show the list of built-in scripts218 and exit immediately.219 </p><p>220 Optionally, write an integer weight after <code class="literal">@</code> to221 adjust the probability of selecting this script versus other ones.222 The default weight is 1.223 See below for details.224 </p></dd><dt id="PGBENCH-OPTION-CLIENT"><span class="term"><code class="option">-c</code> <em class="replaceable"><code>clients</code></em><br /></span><span class="term"><code class="option">--client=</code><em class="replaceable"><code>clients</code></em></span> <a href="#PGBENCH-OPTION-CLIENT" class="id_link">#</a></dt><dd><p>225 Number of clients simulated, that is, number of concurrent database226 sessions. Default is 1.227 </p></dd><dt id="PGBENCH-OPTION-CONNECT"><span class="term"><code class="option">-C</code><br /></span><span class="term"><code class="option">--connect</code></span> <a href="#PGBENCH-OPTION-CONNECT" class="id_link">#</a></dt><dd><p>228 Establish a new connection for each transaction, rather than229 doing it just once per client session.230 This is useful to measure the connection overhead.231 </p></dd><dt id="PGBENCH-OPTION-DEBUG"><span class="term"><code class="option">-d</code><br /></span><span class="term"><code class="option">--debug</code></span> <a href="#PGBENCH-OPTION-DEBUG" class="id_link">#</a></dt><dd><p>232 Print debugging output.233 </p></dd><dt id="PGBENCH-OPTION-DEFINE"><span class="term"><code class="option">-D</code> <em class="replaceable"><code>varname</code></em><code class="literal">=</code><em class="replaceable"><code>value</code></em><br /></span><span class="term"><code class="option">--define=</code><em class="replaceable"><code>varname</code></em><code class="literal">=</code><em class="replaceable"><code>value</code></em></span> <a href="#PGBENCH-OPTION-DEFINE" class="id_link">#</a></dt><dd><p>234 Define a variable for use by a custom script (see below).235 Multiple <code class="option">-D</code> options are allowed.236 </p></dd><dt id="PGBENCH-OPTION-FILE"><span class="term"><code class="option">-f</code> <em class="replaceable"><code>filename[@weight]</code></em><br /></span><span class="term"><code class="option">--file=</code><em class="replaceable"><code>filename[@weight]</code></em></span> <a href="#PGBENCH-OPTION-FILE" class="id_link">#</a></dt><dd><p>237 Add a transaction script read from <em class="replaceable"><code>filename</code></em>238 to the list of scripts to be executed.239 </p><p>240 Optionally, write an integer weight after <code class="literal">@</code> to241 adjust the probability of selecting this script versus other ones.242 The default weight is 1.243 (To use a script file name that includes an <code class="literal">@</code>244 character, append a weight so that there is no ambiguity, for245 example <code class="literal">filen@me@1</code>.)246 See below for details.247 </p></dd><dt id="PGBENCH-OPTION-JOBS"><span class="term"><code class="option">-j</code> <em class="replaceable"><code>threads</code></em><br /></span><span class="term"><code class="option">--jobs=</code><em class="replaceable"><code>threads</code></em></span> <a href="#PGBENCH-OPTION-JOBS" class="id_link">#</a></dt><dd><p>248 Number of worker threads within <span class="application">pgbench</span>.249 Using more than one thread can be helpful on multi-CPU machines.250 Clients are distributed as evenly as possible among available threads.251 Default is 1.252 </p></dd><dt id="PGBENCH-OPTION-LOG"><span class="term"><code class="option">-l</code><br /></span><span class="term"><code class="option">--log</code></span> <a href="#PGBENCH-OPTION-LOG" class="id_link">#</a></dt><dd><p>253 Write information about each transaction to a log file.254 See below for details.255 </p></dd><dt id="PGBENCH-OPTION-LATENCY-LIMIT"><span class="term"><code class="option">-L</code> <em class="replaceable"><code>limit</code></em><br /></span><span class="term"><code class="option">--latency-limit=</code><em class="replaceable"><code>limit</code></em></span> <a href="#PGBENCH-OPTION-LATENCY-LIMIT" class="id_link">#</a></dt><dd><p>256 Transactions that last more than <em class="replaceable"><code>limit</code></em> milliseconds257 are counted and reported separately, as <em class="firstterm">late</em>.258 </p><p>259 When throttling is used (<code class="option">--rate=...</code>), transactions that260 lag behind schedule by more than <em class="replaceable"><code>limit</code></em> ms, and thus261 have no hope of meeting the latency limit, are not sent to the server262 at all. They are counted and reported separately as263 <em class="firstterm">skipped</em>.264 </p><p>265 When the <code class="option">--max-tries</code> option is used, a transaction266 which fails due to a serialization anomaly or from a deadlock will not267 be retried if the total time of all its tries is greater than268 <em class="replaceable"><code>limit</code></em> ms. To limit only the time of tries269 and not their number, use <code class="literal">--max-tries=0</code>. By270 default, the option <code class="option">--max-tries</code> is set to 1 and271 transactions with serialization/deadlock errors are not retried. See272 <a class="xref" href="pgbench.html#FAILURES-AND-RETRIES" title="Failures and Serialization/Deadlock Retries">Failures and Serialization/Deadlock Retries</a> for more information about273 retrying such transactions.274 </p></dd><dt id="PGBENCH-OPTION-PROTOCOL"><span class="term"><code class="option">-M</code> <em class="replaceable"><code>querymode</code></em><br /></span><span class="term"><code class="option">--protocol=</code><em class="replaceable"><code>querymode</code></em></span> <a href="#PGBENCH-OPTION-PROTOCOL" class="id_link">#</a></dt><dd><p>275 Protocol to use for submitting queries to the server:276 </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><code class="literal">simple</code>: use simple query protocol.</p></li><li class="listitem"><p><code class="literal">extended</code>: use extended query protocol.</p></li><li class="listitem"><p><code class="literal">prepared</code>: use extended query protocol with prepared statements.</p></li></ul></div><p>277 278 In the <code class="literal">prepared</code> mode, <span class="application">pgbench</span>279 reuses the parse analysis result starting from the second query280 iteration, so <span class="application">pgbench</span> runs faster281 than in other modes.282 </p><p>283 The default is simple query protocol. (See <a class="xref" href="protocol.html" title="Chapter 55. Frontend/Backend Protocol">Chapter 55</a>284 for more information.)285 </p></dd><dt id="PGBENCH-OPTION-NO-VACUUM-RUN"><span class="term"><code class="option">-n</code><br /></span><span class="term"><code class="option">--no-vacuum</code></span> <a href="#PGBENCH-OPTION-NO-VACUUM-RUN" class="id_link">#</a></dt><dd><p>286 Perform no vacuuming before running the test.287 This option is <span class="emphasis"><em>necessary</em></span>288 if you are running a custom test scenario that does not include289 the standard tables <code class="structname">pgbench_accounts</code>,290 <code class="structname">pgbench_branches</code>, <code class="structname">pgbench_history</code>, and291 <code class="structname">pgbench_tellers</code>.292 </p></dd><dt id="PGBENCH-OPTION-SKIP-SOME-UPDATES"><span class="term"><code class="option">-N</code><br /></span><span class="term"><code class="option">--skip-some-updates</code></span> <a href="#PGBENCH-OPTION-SKIP-SOME-UPDATES" class="id_link">#</a></dt><dd><p>293 Run built-in simple-update script.294 Shorthand for <code class="option">-b simple-update</code>.295 </p></dd><dt id="PGBENCH-OPTION-PROGRESS"><span class="term"><code class="option">-P</code> <em class="replaceable"><code>sec</code></em><br /></span><span class="term"><code class="option">--progress=</code><em class="replaceable"><code>sec</code></em></span> <a href="#PGBENCH-OPTION-PROGRESS" class="id_link">#</a></dt><dd><p>296 Show progress report every <em class="replaceable"><code>sec</code></em> seconds. The report297 includes the time since the beginning of the run, the TPS since the298 last report, and the transaction latency average, standard deviation,299 and the number of failed transactions since the last report. Under300 throttling (<code class="option">-R</code>), the latency is computed with respect301 to the transaction scheduled start time, not the actual transaction302 beginning time, thus it also includes the average schedule lag time.303 When <code class="option">--max-tries</code> is used to enable transaction retries304 after serialization/deadlock errors, the report includes the number of305 retried transactions and the sum of all retries.306 </p></dd><dt id="PGBENCH-OPTION-REPORT-LATENCIES"><span class="term"><code class="option">-r</code><br /></span><span class="term"><code class="option">--report-per-command</code></span> <a href="#PGBENCH-OPTION-REPORT-LATENCIES" class="id_link">#</a></dt><dd><p>307 Report the following statistics for each command after the benchmark308 finishes: the average per-statement latency (execution time from the309 perspective of the client), the number of failures, and the number of310 retries after serialization or deadlock errors in this command. The311 report displays retry statistics only if the312 <code class="option">--max-tries</code> option is not equal to 1.313 </p></dd><dt id="PGBENCH-OPTION-RATE"><span class="term"><code class="option">-R</code> <em class="replaceable"><code>rate</code></em><br /></span><span class="term"><code class="option">--rate=</code><em class="replaceable"><code>rate</code></em></span> <a href="#PGBENCH-OPTION-RATE" class="id_link">#</a></dt><dd><p>314 Execute transactions targeting the specified rate instead of running315 as fast as possible (the default). The rate is given in transactions316 per second. If the targeted rate is above the maximum possible rate,317 the rate limit won't impact the results.318 </p><p>319 The rate is targeted by starting transactions along a320 Poisson-distributed schedule time line. The expected start time321 schedule moves forward based on when the client first started, not322 when the previous transaction ended. That approach means that when323 transactions go past their original scheduled end time, it is324 possible for later ones to catch up again.325 </p><p>326 When throttling is active, the transaction latency reported at the327 end of the run is calculated from the scheduled start times, so it328 includes the time each transaction had to wait for the previous329 transaction to finish. The wait time is called the schedule lag time,330 and its average and maximum are also reported separately. The331 transaction latency with respect to the actual transaction start time,332 i.e., the time spent executing the transaction in the database, can be333 computed by subtracting the schedule lag time from the reported334 latency.335 </p><p>336 If <code class="option">--latency-limit</code> is used together with <code class="option">--rate</code>,337 a transaction can lag behind so much that it is already over the338 latency limit when the previous transaction ends, because the latency339 is calculated from the scheduled start time. Such transactions are340 not sent to the server, but are skipped altogether and counted341 separately.342 </p><p>343 A high schedule lag time is an indication that the system cannot344 process transactions at the specified rate, with the chosen number of345 clients and threads. When the average transaction execution time is346 longer than the scheduled interval between each transaction, each347 successive transaction will fall further behind, and the schedule lag348 time will keep increasing the longer the test run is. When that349 happens, you will have to reduce the specified transaction rate.350 </p></dd><dt id="PGBENCH-OPTION-SCALE-RUN"><span class="term"><code class="option">-s</code> <em class="replaceable"><code>scale_factor</code></em><br /></span><span class="term"><code class="option">--scale=</code><em class="replaceable"><code>scale_factor</code></em></span> <a href="#PGBENCH-OPTION-SCALE-RUN" class="id_link">#</a></dt><dd><p>351 Report the specified scale factor in <span class="application">pgbench</span>'s352 output. With the built-in tests, this is not necessary; the353 correct scale factor will be detected by counting the number of354 rows in the <code class="structname">pgbench_branches</code> table.355 However, when testing only custom benchmarks (<code class="option">-f</code> option),356 the scale factor will be reported as 1 unless this option is used.357 </p></dd><dt id="PGBENCH-OPTION-SELECT-ONLY"><span class="term"><code class="option">-S</code><br /></span><span class="term"><code class="option">--select-only</code></span> <a href="#PGBENCH-OPTION-SELECT-ONLY" class="id_link">#</a></dt><dd><p>358 Run built-in select-only script.359 Shorthand for <code class="option">-b select-only</code>.360 </p></dd><dt id="PGBENCH-OPTION-TRANSACTIONS"><span class="term"><code class="option">-t</code> <em class="replaceable"><code>transactions</code></em><br /></span><span class="term"><code class="option">--transactions=</code><em class="replaceable"><code>transactions</code></em></span> <a href="#PGBENCH-OPTION-TRANSACTIONS" class="id_link">#</a></dt><dd><p>361 Number of transactions each client runs. Default is 10.362 </p></dd><dt id="PGBENCH-OPTION-TIME"><span class="term"><code class="option">-T</code> <em class="replaceable"><code>seconds</code></em><br /></span><span class="term"><code class="option">--time=</code><em class="replaceable"><code>seconds</code></em></span> <a href="#PGBENCH-OPTION-TIME" class="id_link">#</a></dt><dd><p>363 Run the test for this many seconds, rather than a fixed number of364 transactions per client. <code class="option">-t</code> and365 <code class="option">-T</code> are mutually exclusive.366 </p></dd><dt id="PGBENCH-OPTION-VACUUM-ALL"><span class="term"><code class="option">-v</code><br /></span><span class="term"><code class="option">--vacuum-all</code></span> <a href="#PGBENCH-OPTION-VACUUM-ALL" class="id_link">#</a></dt><dd><p>367 Vacuum all four standard tables before running the test.368 With neither <code class="option">-n</code> nor <code class="option">-v</code>, <span class="application">pgbench</span> will vacuum the369 <code class="structname">pgbench_tellers</code> and <code class="structname">pgbench_branches</code>370 tables, and will truncate <code class="structname">pgbench_history</code>.371 </p></dd><dt id="PGBENCH-OPTION-AGGREGATE-INTERVAL"><span class="term"><code class="option">--aggregate-interval=<em class="replaceable"><code>seconds</code></em></code></span> <a href="#PGBENCH-OPTION-AGGREGATE-INTERVAL" class="id_link">#</a></dt><dd><p>372 Length of aggregation interval (in seconds). May be used only373 with <code class="option">-l</code> option. With this option, the log contains374 per-interval summary data, as described below.375 </p></dd><dt id="PGBENCH-OPTION-FAILURES-DETAILED"><span class="term"><code class="option">--failures-detailed</code></span> <a href="#PGBENCH-OPTION-FAILURES-DETAILED" class="id_link">#</a></dt><dd><p>376 Report failures in per-transaction and aggregation logs, as well as in377 the main and per-script reports, grouped by the following types:378 </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>serialization failures;</p></li><li class="listitem"><p>deadlock failures;</p></li></ul></div><p>379 See <a class="xref" href="pgbench.html#FAILURES-AND-RETRIES" title="Failures and Serialization/Deadlock Retries">Failures and Serialization/Deadlock Retries</a> for more information.380 </p></dd><dt id="PGBENCH-OPTION-LOG-PREFIX"><span class="term"><code class="option">--log-prefix=<em class="replaceable"><code>prefix</code></em></code></span> <a href="#PGBENCH-OPTION-LOG-PREFIX" class="id_link">#</a></dt><dd><p>381 Set the filename prefix for the log files created by382 <code class="option">--log</code>. The default is <code class="literal">pgbench_log</code>.383 </p></dd><dt id="PGBENCH-OPTION-MAX-TRIES"><span class="term"><code class="option">--max-tries=<em class="replaceable"><code>number_of_tries</code></em></code></span> <a href="#PGBENCH-OPTION-MAX-TRIES" class="id_link">#</a></dt><dd><p>384 Enable retries for transactions with serialization/deadlock errors and385 set the maximum number of these tries. This option can be combined with386 the <code class="option">--latency-limit</code> option which limits the total time387 of all transaction tries; moreover, you cannot use an unlimited number388 of tries (<code class="literal">--max-tries=0</code>) without389 <code class="option">--latency-limit</code> or <code class="option">--time</code>.390 The default value is 1 and transactions with serialization/deadlock391 errors are not retried. See <a class="xref" href="pgbench.html#FAILURES-AND-RETRIES" title="Failures and Serialization/Deadlock Retries">Failures and Serialization/Deadlock Retries</a>392 for more information about retrying such transactions.393 </p></dd><dt id="PGBENCH-OPTION-PROGRESS-TIMESTAMP"><span class="term"><code class="option">--progress-timestamp</code></span> <a href="#PGBENCH-OPTION-PROGRESS-TIMESTAMP" class="id_link">#</a></dt><dd><p>394 When showing progress (option <code class="option">-P</code>), use a timestamp395 (Unix epoch) instead of the number of seconds since the396 beginning of the run. The unit is in seconds, with millisecond397 precision after the dot.398 This helps compare logs generated by various tools.399 </p></dd><dt id="PGBENCH-OPTION-RANDOM-SEED"><span class="term"><code class="option">--random-seed=</code><em class="replaceable"><code>seed</code></em></span> <a href="#PGBENCH-OPTION-RANDOM-SEED" class="id_link">#</a></dt><dd><p>400 Set random generator seed. Seeds the system random number generator,401 which then produces a sequence of initial generator states, one for402 each thread.403 Values for <em class="replaceable"><code>seed</code></em> may be:404 <code class="literal">time</code> (the default, the seed is based on the current time),405 <code class="literal">rand</code> (use a strong random source, failing if none406 is available), or an unsigned decimal integer value.407 The random generator is invoked explicitly from a pgbench script408 (<code class="literal">random...</code> functions) or implicitly (for instance option409 <code class="option">--rate</code> uses it to schedule transactions).410 When explicitly set, the value used for seeding is shown on the terminal.411 Any value allowed for <em class="replaceable"><code>seed</code></em> may also be412 provided through the environment variable413 <code class="literal">PGBENCH_RANDOM_SEED</code>.414 To ensure that the provided seed impacts all possible uses, put this option415 first or use the environment variable.416 </p><p>417 Setting the seed explicitly allows to reproduce a <code class="command">pgbench</code>418 run exactly, as far as random numbers are concerned.419 As the random state is managed per thread, this means the exact same420 <code class="command">pgbench</code> run for an identical invocation if there is one421 client per thread and there are no external or data dependencies.422 From a statistical viewpoint reproducing runs exactly is a bad idea because423 it can hide the performance variability or improve performance unduly,424 e.g., by hitting the same pages as a previous run.425 However, it may also be of great help for debugging, for instance426 re-running a tricky case which leads to an error.427 Use wisely.428 </p></dd><dt id="PGBENCH-OPTION-SAMPLING-RATE"><span class="term"><code class="option">--sampling-rate=<em class="replaceable"><code>rate</code></em></code></span> <a href="#PGBENCH-OPTION-SAMPLING-RATE" class="id_link">#</a></dt><dd><p>429 Sampling rate, used when writing data into the log, to reduce the430 amount of log generated. If this option is given, only the specified431 fraction of transactions are logged. 1.0 means all transactions will432 be logged, 0.05 means only 5% of the transactions will be logged.433 </p><p>434 Remember to take the sampling rate into account when processing the435 log file. For example, when computing TPS values, you need to multiply436 the numbers accordingly (e.g., with 0.01 sample rate, you'll only get437 1/100 of the actual TPS).438 </p></dd><dt id="PGBENCH-OPTION-SHOW-SCRIPT"><span class="term"><code class="option">--show-script=</code><em class="replaceable"><code>scriptname</code></em></span> <a href="#PGBENCH-OPTION-SHOW-SCRIPT" class="id_link">#</a></dt><dd><p>439 Show the actual code of builtin script <em class="replaceable"><code>scriptname</code></em>440 on stderr, and exit immediately.441 </p></dd><dt id="PGBENCH-OPTION-VERBOSE-ERRORS"><span class="term"><code class="option">--verbose-errors</code></span> <a href="#PGBENCH-OPTION-VERBOSE-ERRORS" class="id_link">#</a></dt><dd><p>442 Print messages about all errors and failures (errors without retrying)443 including which limit for retries was exceeded and how far it was444 exceeded for the serialization/deadlock failures. (Note that in this445 case the output can be significantly increased.).446 See <a class="xref" href="pgbench.html#FAILURES-AND-RETRIES" title="Failures and Serialization/Deadlock Retries">Failures and Serialization/Deadlock Retries</a> for more information.447 </p></dd></dl></div><p>448 </p></div><div class="refsect2" id="PGBENCH-COMMON-OPTIONS"><h3>Common Options</h3><p>449 <span class="application">pgbench</span> also accepts the following common command-line450 arguments for connection parameters:451 452 </p><div class="variablelist"><dl class="variablelist"><dt id="PGBENCH-OPTION-HOST"><span class="term"><code class="option">-h</code> <em class="replaceable"><code>hostname</code></em><br /></span><span class="term"><code class="option">--host=</code><em class="replaceable"><code>hostname</code></em></span> <a href="#PGBENCH-OPTION-HOST" class="id_link">#</a></dt><dd><p>453 The database server's host name454 </p></dd><dt id="PGBENCH-OPTION-PORT"><span class="term"><code class="option">-p</code> <em class="replaceable"><code>port</code></em><br /></span><span class="term"><code class="option">--port=</code><em class="replaceable"><code>port</code></em></span> <a href="#PGBENCH-OPTION-PORT" class="id_link">#</a></dt><dd><p>455 The database server's port number456 </p></dd><dt id="PGBENCH-OPTION-USERNAME"><span class="term"><code class="option">-U</code> <em class="replaceable"><code>login</code></em><br /></span><span class="term"><code class="option">--username=</code><em class="replaceable"><code>login</code></em></span> <a href="#PGBENCH-OPTION-USERNAME" class="id_link">#</a></dt><dd><p>457 The user name to connect as458 </p></dd><dt id="PGBENCH-OPTION-VERSION"><span class="term"><code class="option">-V</code><br /></span><span class="term"><code class="option">--version</code></span> <a href="#PGBENCH-OPTION-VERSION" class="id_link">#</a></dt><dd><p>459 Print the <span class="application">pgbench</span> version and exit.460 </p></dd><dt id="PGBENCH-OPTION-HELP"><span class="term"><code class="option">-?</code><br /></span><span class="term"><code class="option">--help</code></span> <a href="#PGBENCH-OPTION-HELP" class="id_link">#</a></dt><dd><p>461 Show help about <span class="application">pgbench</span> command line462 arguments, and exit.463 </p></dd></dl></div><p>464 </p></div></div><div class="refsect1" id="id-1.9.4.11.7"><h2>Exit Status</h2><p>465 A successful run will exit with status 0. Exit status 1 indicates static466 problems such as invalid command-line options or internal errors which467 are supposed to never occur. Early errors that occur when starting468 benchmark such as initial connection failures also exit with status 1.469 Errors during the run such as database errors or problems in the script470 will result in exit status 2. In the latter case,471 <span class="application">pgbench</span> will print partial results.472 </p></div><div class="refsect1" id="id-1.9.4.11.8"><h2>Environment</h2><div class="variablelist"><dl class="variablelist"><dt id="PGBENCH-ENVIRONMENT-PGDATABASE"><span class="term"><code class="envar">PGDATABASE</code><br /></span><span class="term"><code class="envar">PGHOST</code><br /></span><span class="term"><code class="envar">PGPORT</code><br /></span><span class="term"><code class="envar">PGUSER</code></span> <a href="#PGBENCH-ENVIRONMENT-PGDATABASE" class="id_link">#</a></dt><dd><p>473 Default connection parameters.474 </p></dd></dl></div><p>475 This utility, like most other <span class="productname">PostgreSQL</span> utilities,476 uses the environment variables supported by <span class="application">libpq</span>477 (see <a class="xref" href="libpq-envars.html" title="34.15. Environment Variables">Section 34.15</a>).478 </p><p>479 The environment variable <code class="envar">PG_COLOR</code> specifies whether to use480 color in diagnostic messages. Possible values are481 <code class="literal">always</code>, <code class="literal">auto</code> and482 <code class="literal">never</code>.483 </p></div><div class="refsect1" id="id-1.9.4.11.9"><h2>Notes</h2><div class="refsect2" id="TRANSACTIONS-AND-SCRIPTS"><h3>What Is the <span class="quote">“<span class="quote">Transaction</span>”</span> Actually Performed in <span class="application">pgbench</span>?</h3><p>484 <span class="application">pgbench</span> executes test scripts chosen randomly485 from a specified list.486 The scripts may include built-in scripts specified with <code class="option">-b</code>487 and user-provided scripts specified with <code class="option">-f</code>.488 Each script may be given a relative weight specified after an489 <code class="literal">@</code> so as to change its selection probability.490 The default weight is <code class="literal">1</code>.491 Scripts with a weight of <code class="literal">0</code> are ignored.492 </p><p>493 The default built-in transaction script (also invoked with <code class="option">-b tpcb-like</code>)494 issues seven commands per transaction over randomly chosen <code class="literal">aid</code>,495 <code class="literal">tid</code>, <code class="literal">bid</code> and <code class="literal">delta</code>.496 The scenario is inspired by the TPC-B benchmark, but is not actually TPC-B,497 hence the name.498 </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p><code class="literal">BEGIN;</code></p></li><li class="listitem"><p><code class="literal">UPDATE pgbench_accounts SET abalance = abalance + :delta WHERE aid = :aid;</code></p></li><li class="listitem"><p><code class="literal">SELECT abalance FROM pgbench_accounts WHERE aid = :aid;</code></p></li><li class="listitem"><p><code class="literal">UPDATE pgbench_tellers SET tbalance = tbalance + :delta WHERE tid = :tid;</code></p></li><li class="listitem"><p><code class="literal">UPDATE pgbench_branches SET bbalance = bbalance + :delta WHERE bid = :bid;</code></p></li><li class="listitem"><p><code class="literal">INSERT INTO pgbench_history (tid, bid, aid, delta, mtime) VALUES (:tid, :bid, :aid, :delta, CURRENT_TIMESTAMP);</code></p></li><li class="listitem"><p><code class="literal">END;</code></p></li></ol></div><p>499 If you select the <code class="literal">simple-update</code> built-in (also <code class="option">-N</code>),500 steps 4 and 5 aren't included in the transaction.501 This will avoid update contention on these tables, but502 it makes the test case even less like TPC-B.503 </p><p>504 If you select the <code class="literal">select-only</code> built-in (also <code class="option">-S</code>),505 only the <code class="command">SELECT</code> is issued.506 </p></div><div class="refsect2" id="id-1.9.4.11.9.3"><h3>Custom Scripts</h3><p>507 <span class="application">pgbench</span> has support for running custom508 benchmark scenarios by replacing the default transaction script509 (described above) with a transaction script read from a file510 (<code class="option">-f</code> option). In this case a <span class="quote">“<span class="quote">transaction</span>”</span>511 counts as one execution of a script file.512 </p><p>513 A script file contains one or more SQL commands terminated by514 semicolons. Empty lines and lines beginning with515 <code class="literal">--</code> are ignored. Script files can also contain516 <span class="quote">“<span class="quote">meta commands</span>”</span>, which are interpreted by <span class="application">pgbench</span>517 itself, as described below.518 </p><div class="note"><h3 class="title">Note</h3><p>519 Before <span class="productname">PostgreSQL</span> 9.6, SQL commands in script files520 were terminated by newlines, and so they could not be continued across521 lines. Now a semicolon is <span class="emphasis"><em>required</em></span> to separate consecutive522 SQL commands (though an SQL command does not need one if it is followed523 by a meta command). If you need to create a script file that works with524 both old and new versions of <span class="application">pgbench</span>, be sure to write525 each SQL command on a single line ending with a semicolon.526 </p><p>527 It is assumed that pgbench scripts do not contain incomplete blocks of SQL528 transactions. If at runtime the client reaches the end of the script without529 completing the last transaction block, it will be aborted.530 </p></div><p>531 There is a simple variable-substitution facility for script files.532 Variable names must consist of letters (including non-Latin letters),533 digits, and underscores, with the first character not being a digit.534 Variables can be set by the command-line <code class="option">-D</code> option,535 explained above, or by the meta commands explained below.536 In addition to any variables preset by <code class="option">-D</code> command-line options,537 there are a few variables that are preset automatically, listed in538 <a class="xref" href="pgbench.html#PGBENCH-AUTOMATIC-VARIABLES" title="Table 293. pgbench Automatic Variables">Table 293</a>. A value specified for these539 variables using <code class="option">-D</code> takes precedence over the automatic presets.540 Once set, a variable's541 value can be inserted into an SQL command by writing542 <code class="literal">:</code><em class="replaceable"><code>variablename</code></em>. When running more than543 one client session, each session has its own set of variables.544 <span class="application">pgbench</span> supports up to 255 variable uses in one545 statement.546 </p><div class="table" id="PGBENCH-AUTOMATIC-VARIABLES"><p class="title"><strong>Table 293. pgbench Automatic Variables</strong></p><div class="table-contents"><table class="table" summary="pgbench Automatic Variables" border="1"><colgroup><col class="col1" /><col class="col2" /></colgroup><thead><tr><th>Variable</th><th>Description</th></tr></thead><tbody><tr><td> <code class="literal">client_id</code> </td><td>unique number identifying the client session (starts from zero)</td></tr><tr><td> <code class="literal">default_seed</code> </td><td>seed used in hash and pseudorandom permutation functions by default</td></tr><tr><td> <code class="literal">random_seed</code> </td><td>random generator seed (unless overwritten with <code class="option">-D</code>)</td></tr><tr><td> <code class="literal">scale</code> </td><td>current scale factor</td></tr></tbody></table></div></div><br class="table-break" /><p>547 Script file meta commands begin with a backslash (<code class="literal">\</code>) and548 normally extend to the end of the line, although they can be continued549 to additional lines by writing backslash-return.550 Arguments to a meta command are separated by white space.551 These meta commands are supported:552 </p><div class="variablelist"><dl class="variablelist"><dt id="PGBENCH-METACOMMAND-GSET"><span class="term">553 <code class="literal">\gset [<em class="replaceable"><code>prefix</code></em>]</code>554 <code class="literal">\aset [<em class="replaceable"><code>prefix</code></em>]</code>555 </span> <a href="#PGBENCH-METACOMMAND-GSET" class="id_link">#</a></dt><dd><p>556 These commands may be used to end SQL queries, taking the place of the557 terminating semicolon (<code class="literal">;</code>).558 </p><p>559 When the <code class="literal">\gset</code> command is used, the preceding SQL query is560 expected to return one row, the columns of which are stored into variables561 named after column names, and prefixed with <em class="replaceable"><code>prefix</code></em>562 if provided.563 </p><p>564 When the <code class="literal">\aset</code> command is used, all combined SQL queries565 (separated by <code class="literal">\;</code>) have their columns stored into variables566 named after column names, and prefixed with <em class="replaceable"><code>prefix</code></em>567 if provided. If a query returns no row, no assignment is made and the variable568 can be tested for existence to detect this. If a query returns more than one569 row, the last value is kept.570 </p><p>571 <code class="literal">\gset</code> and <code class="literal">\aset</code> cannot be used in572 pipeline mode, since the query results are not yet available by the time573 the commands would need them.574 </p><p>575 The following example puts the final account balance from the first query576 into variable <em class="replaceable"><code>abalance</code></em>, and fills variables577 <em class="replaceable"><code>p_two</code></em> and <em class="replaceable"><code>p_three</code></em>578 with integers from the third query.579 The result of the second query is discarded.580 The result of the two last combined queries are stored in variables581 <em class="replaceable"><code>four</code></em> and <em class="replaceable"><code>five</code></em>.582</p><pre class="programlisting">583UPDATE pgbench_accounts584 SET abalance = abalance + :delta585 WHERE aid = :aid586 RETURNING abalance \gset587-- compound of two queries588SELECT 1 \;589SELECT 2 AS two, 3 AS three \gset p_590SELECT 4 AS four \; SELECT 5 AS five \aset591</pre></dd><dt id="PGBENCH-METACOMMAND-IF-ELSE"><span class="term"><code class="literal">\if</code> <em class="replaceable"><code>expression</code></em><br /></span><span class="term"><code class="literal">\elif</code> <em class="replaceable"><code>expression</code></em><br /></span><span class="term"><code class="literal">\else</code><br /></span><span class="term"><code class="literal">\endif</code></span> <a href="#PGBENCH-METACOMMAND-IF-ELSE" class="id_link">#</a></dt><dd><p>592 This group of commands implements nestable conditional blocks,593 similarly to <code class="literal">psql</code>'s <a class="xref" href="app-psql.html#PSQL-METACOMMAND-IF"><code class="literal">\if</code> <em class="replaceable"><code>expression</code></em></a>.594 Conditional expressions are identical to those with <code class="literal">\set</code>,595 with non-zero values interpreted as true.596 </p></dd><dt id="PGBENCH-METACOMMAND-SET"><span class="term">597 <code class="literal">\set <em class="replaceable"><code>varname</code></em> <em class="replaceable"><code>expression</code></em></code>598 </span> <a href="#PGBENCH-METACOMMAND-SET" class="id_link">#</a></dt><dd><p>599 Sets variable <em class="replaceable"><code>varname</code></em> to a value calculated600 from <em class="replaceable"><code>expression</code></em>.601 The expression may contain the <code class="literal">NULL</code> constant,602 Boolean constants <code class="literal">TRUE</code> and <code class="literal">FALSE</code>,603 integer constants such as <code class="literal">5432</code>,604 double constants such as <code class="literal">3.14159</code>,605 references to variables <code class="literal">:</code><em class="replaceable"><code>variablename</code></em>,606 <a class="link" href="pgbench.html#PGBENCH-BUILTIN-OPERATORS" title="Built-in Operators">operators</a>607 with their usual SQL precedence and associativity,608 <a class="link" href="pgbench.html#PGBENCH-BUILTIN-FUNCTIONS" title="Built-In Functions">function calls</a>,609 SQL <a class="link" href="functions-conditional.html#FUNCTIONS-CASE" title="9.18.1. CASE"><code class="token">CASE</code> generic conditional610 expressions</a> and parentheses.611 </p><p>612 Functions and most operators return <code class="literal">NULL</code> on613 <code class="literal">NULL</code> input.614 </p><p>615 For conditional purposes, non zero numerical values are616 <code class="literal">TRUE</code>, zero numerical values and <code class="literal">NULL</code>617 are <code class="literal">FALSE</code>.618 </p><p>619 Too large or small integer and double constants, as well as620 integer arithmetic operators (<code class="literal">+</code>,621 <code class="literal">-</code>, <code class="literal">*</code> and <code class="literal">/</code>)622 raise errors on overflows.623 </p><p>624 When no final <code class="token">ELSE</code> clause is provided to a625 <code class="token">CASE</code>, the default value is <code class="literal">NULL</code>.626 </p><p>627 Examples:628</p><pre class="programlisting">629\set ntellers 10 * :scale630\set aid (1021 * random(1, 100000 * :scale)) % \631 (100000 * :scale) + 1632\set divx CASE WHEN :x <> 0 THEN :y/:x ELSE NULL END633</pre></dd><dt id="PGBENCH-METACOMMAND-SLEEP"><span class="term">634 <code class="literal">\sleep <em class="replaceable"><code>number</code></em> [ us | ms | s ]</code>635 </span> <a href="#PGBENCH-METACOMMAND-SLEEP" class="id_link">#</a></dt><dd><p>636 Causes script execution to sleep for the specified duration in637 microseconds (<code class="literal">us</code>), milliseconds (<code class="literal">ms</code>) or seconds638 (<code class="literal">s</code>). If the unit is omitted then seconds are the default.639 <em class="replaceable"><code>number</code></em> can be either an integer constant or a640 <code class="literal">:</code><em class="replaceable"><code>variablename</code></em> reference to a variable641 having an integer value.642 </p><p>643 Example:644</p><pre class="programlisting">645\sleep 10 ms646</pre></dd><dt id="PGBENCH-METACOMMAND-SETSHELL"><span class="term">647 <code class="literal">\setshell <em class="replaceable"><code>varname</code></em> <em class="replaceable"><code>command</code></em> [ <em class="replaceable"><code>argument</code></em> ... ]</code>648 </span> <a href="#PGBENCH-METACOMMAND-SETSHELL" class="id_link">#</a></dt><dd><p>649 Sets variable <em class="replaceable"><code>varname</code></em> to the result of the shell command650 <em class="replaceable"><code>command</code></em> with the given <em class="replaceable"><code>argument</code></em>(s).651 The command must return an integer value through its standard output.652 </p><p>653 <em class="replaceable"><code>command</code></em> and each <em class="replaceable"><code>argument</code></em> can be either654 a text constant or a <code class="literal">:</code><em class="replaceable"><code>variablename</code></em> reference655 to a variable. If you want to use an <em class="replaceable"><code>argument</code></em> starting656 with a colon, write an additional colon at the beginning of657 <em class="replaceable"><code>argument</code></em>.658 </p><p>659 Example:660</p><pre class="programlisting">661\setshell variable_to_be_assigned command literal_argument :variable ::literal_starting_with_colon662</pre></dd><dt id="PGBENCH-METACOMMAND-SHELL"><span class="term">663 <code class="literal">\shell <em class="replaceable"><code>command</code></em> [ <em class="replaceable"><code>argument</code></em> ... ]</code>664 </span> <a href="#PGBENCH-METACOMMAND-SHELL" class="id_link">#</a></dt><dd><p>665 Same as <code class="literal">\setshell</code>, but the result of the command666 is discarded.667 </p><p>668 Example:669</p><pre class="programlisting">670\shell command literal_argument :variable ::literal_starting_with_colon671</pre></dd><dt id="PGBENCH-METACOMMAND-PIPELINE"><span class="term"><code class="literal">\startpipeline</code><br /></span><span class="term"><code class="literal">\endpipeline</code></span> <a href="#PGBENCH-METACOMMAND-PIPELINE" class="id_link">#</a></dt><dd><p>672 These commands delimit the start and end of a pipeline of SQL673 statements. In pipeline mode, statements are sent to the server674 without waiting for the results of previous statements. See675 <a class="xref" href="libpq-pipeline-mode.html" title="34.5. Pipeline Mode">Section 34.5</a> for more details.676 Pipeline mode requires the use of extended query protocol.677 </p></dd></dl></div></div><div class="refsect2" id="PGBENCH-BUILTIN-OPERATORS"><h3>Built-in Operators</h3><p>678 The arithmetic, bitwise, comparison and logical operators listed in679 <a class="xref" href="pgbench.html#PGBENCH-OPERATORS" title="Table 294. pgbench Operators">Table 294</a> are built into <span class="application">pgbench</span>680 and may be used in expressions appearing in681 <a class="link" href="pgbench.html#PGBENCH-METACOMMAND-SET"><code class="literal">\set</code></a>.682 The operators are listed in increasing precedence order.683 Except as noted, operators taking two numeric inputs will produce684 a double value if either input is double, otherwise they produce685 an integer result.686 </p><div class="table" id="PGBENCH-OPERATORS"><p class="title"><strong>Table 294. pgbench Operators</strong></p><div class="table-contents"><table class="table" summary="pgbench Operators" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">687 Operator688 </p>689 <p>690 Description691 </p>692 <p>693 Example(s)694 </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">695 <em class="replaceable"><code>boolean</code></em> <code class="literal">OR</code> <em class="replaceable"><code>boolean</code></em>696 → <code class="returnvalue"><em class="replaceable"><code>boolean</code></em></code>697 </p>698 <p>699 Logical OR700 </p>701 <p>702 <code class="literal">5 or 0</code>703 → <code class="returnvalue">TRUE</code>704 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">705 <em class="replaceable"><code>boolean</code></em> <code class="literal">AND</code> <em class="replaceable"><code>boolean</code></em>706 → <code class="returnvalue"><em class="replaceable"><code>boolean</code></em></code>707 </p>708 <p>709 Logical AND710 </p>711 <p>712 <code class="literal">3 and 0</code>713 → <code class="returnvalue">FALSE</code>714 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">715 <code class="literal">NOT</code> <em class="replaceable"><code>boolean</code></em>716 → <code class="returnvalue"><em class="replaceable"><code>boolean</code></em></code>717 </p>718 <p>719 Logical NOT720 </p>721 <p>722 <code class="literal">not false</code>723 → <code class="returnvalue">TRUE</code>724 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">725 <em class="replaceable"><code>boolean</code></em> <code class="literal">IS [NOT] (NULL|TRUE|FALSE)</code>726 → <code class="returnvalue"><em class="replaceable"><code>boolean</code></em></code>727 </p>728 <p>729 Boolean value tests730 </p>731 <p>732 <code class="literal">1 is null</code>733 → <code class="returnvalue">FALSE</code>734 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">735 <em class="replaceable"><code>value</code></em> <code class="literal">ISNULL|NOTNULL</code>736 → <code class="returnvalue"><em class="replaceable"><code>boolean</code></em></code>737 </p>738 <p>739 Nullness tests740 </p>741 <p>742 <code class="literal">1 notnull</code>743 → <code class="returnvalue">TRUE</code>744 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">745 <em class="replaceable"><code>number</code></em> <code class="literal">=</code> <em class="replaceable"><code>number</code></em>746 → <code class="returnvalue"><em class="replaceable"><code>boolean</code></em></code>747 </p>748 <p>749 Equal750 </p>751 <p>752 <code class="literal">5 = 4</code>753 → <code class="returnvalue">FALSE</code>754 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">755 <em class="replaceable"><code>number</code></em> <code class="literal"><></code> <em class="replaceable"><code>number</code></em>756 → <code class="returnvalue"><em class="replaceable"><code>boolean</code></em></code>757 </p>758 <p>759 Not equal760 </p>761 <p>762 <code class="literal">5 <> 4</code>763 → <code class="returnvalue">TRUE</code>764 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">765 <em class="replaceable"><code>number</code></em> <code class="literal">!=</code> <em class="replaceable"><code>number</code></em>766 → <code class="returnvalue"><em class="replaceable"><code>boolean</code></em></code>767 </p>768 <p>769 Not equal770 </p>771 <p>772 <code class="literal">5 != 5</code>773 → <code class="returnvalue">FALSE</code>774 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">775 <em class="replaceable"><code>number</code></em> <code class="literal"><</code> <em class="replaceable"><code>number</code></em>776 → <code class="returnvalue"><em class="replaceable"><code>boolean</code></em></code>777 </p>778 <p>779 Less than780 </p>781 <p>782 <code class="literal">5 < 4</code>783 → <code class="returnvalue">FALSE</code>784 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">785 <em class="replaceable"><code>number</code></em> <code class="literal"><=</code> <em class="replaceable"><code>number</code></em>786 → <code class="returnvalue"><em class="replaceable"><code>boolean</code></em></code>787 </p>788 <p>789 Less than or equal to790 </p>791 <p>792 <code class="literal">5 <= 4</code>793 → <code class="returnvalue">FALSE</code>794 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">795 <em class="replaceable"><code>number</code></em> <code class="literal">></code> <em class="replaceable"><code>number</code></em>796 → <code class="returnvalue"><em class="replaceable"><code>boolean</code></em></code>797 </p>798 <p>799 Greater than800 </p>801 <p>802 <code class="literal">5 > 4</code>803 → <code class="returnvalue">TRUE</code>804 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">805 <em class="replaceable"><code>number</code></em> <code class="literal">>=</code> <em class="replaceable"><code>number</code></em>806 → <code class="returnvalue"><em class="replaceable"><code>boolean</code></em></code>807 </p>808 <p>809 Greater than or equal to810 </p>811 <p>812 <code class="literal">5 >= 4</code>813 → <code class="returnvalue">TRUE</code>814 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">815 <em class="replaceable"><code>integer</code></em> <code class="literal">|</code> <em class="replaceable"><code>integer</code></em>816 → <code class="returnvalue"><em class="replaceable"><code>integer</code></em></code>817 </p>818 <p>819 Bitwise OR820 </p>821 <p>822 <code class="literal">1 | 2</code>823 → <code class="returnvalue">3</code>824 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">825 <em class="replaceable"><code>integer</code></em> <code class="literal">#</code> <em class="replaceable"><code>integer</code></em>826 → <code class="returnvalue"><em class="replaceable"><code>integer</code></em></code>827 </p>828 <p>829 Bitwise XOR830 </p>831 <p>832 <code class="literal">1 # 3</code>833 → <code class="returnvalue">2</code>834 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">835 <em class="replaceable"><code>integer</code></em> <code class="literal">&</code> <em class="replaceable"><code>integer</code></em>836 → <code class="returnvalue"><em class="replaceable"><code>integer</code></em></code>837 </p>838 <p>839 Bitwise AND840 </p>841 <p>842 <code class="literal">1 & 3</code>843 → <code class="returnvalue">1</code>844 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">845 <code class="literal">~</code> <em class="replaceable"><code>integer</code></em>846 → <code class="returnvalue"><em class="replaceable"><code>integer</code></em></code>847 </p>848 <p>849 Bitwise NOT850 </p>851 <p>852 <code class="literal">~ 1</code>853 → <code class="returnvalue">-2</code>854 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">855 <em class="replaceable"><code>integer</code></em> <code class="literal"><<</code> <em class="replaceable"><code>integer</code></em>856 → <code class="returnvalue"><em class="replaceable"><code>integer</code></em></code>857 </p>858 <p>859 Bitwise shift left860 </p>861 <p>862 <code class="literal">1 << 2</code>863 → <code class="returnvalue">4</code>864 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">865 <em class="replaceable"><code>integer</code></em> <code class="literal">>></code> <em class="replaceable"><code>integer</code></em>866 → <code class="returnvalue"><em class="replaceable"><code>integer</code></em></code>867 </p>868 <p>869 Bitwise shift right870 </p>871 <p>872 <code class="literal">8 >> 2</code>873 → <code class="returnvalue">2</code>874 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">875 <em class="replaceable"><code>number</code></em> <code class="literal">+</code> <em class="replaceable"><code>number</code></em>876 → <code class="returnvalue"><em class="replaceable"><code>number</code></em></code>877 </p>878 <p>879 Addition880 </p>881 <p>882 <code class="literal">5 + 4</code>883 → <code class="returnvalue">9</code>884 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">885 <em class="replaceable"><code>number</code></em> <code class="literal">-</code> <em class="replaceable"><code>number</code></em>886 → <code class="returnvalue"><em class="replaceable"><code>number</code></em></code>887 </p>888 <p>889 Subtraction890 </p>891 <p>892 <code class="literal">3 - 2.0</code>893 → <code class="returnvalue">1.0</code>894 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">895 <em class="replaceable"><code>number</code></em> <code class="literal">*</code> <em class="replaceable"><code>number</code></em>896 → <code class="returnvalue"><em class="replaceable"><code>number</code></em></code>897 </p>898 <p>899 Multiplication900 </p>901 <p>902 <code class="literal">5 * 4</code>903 → <code class="returnvalue">20</code>904 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">905 <em class="replaceable"><code>number</code></em> <code class="literal">/</code> <em class="replaceable"><code>number</code></em>906 → <code class="returnvalue"><em class="replaceable"><code>number</code></em></code>907 </p>908 <p>909 Division (truncates the result towards zero if both inputs are integers)910 </p>911 <p>912 <code class="literal">5 / 3</code>913 → <code class="returnvalue">1</code>914 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">915 <em class="replaceable"><code>integer</code></em> <code class="literal">%</code> <em class="replaceable"><code>integer</code></em>916 → <code class="returnvalue"><em class="replaceable"><code>integer</code></em></code>917 </p>918 <p>919 Modulo (remainder)920 </p>921 <p>922 <code class="literal">3 % 2</code>923 → <code class="returnvalue">1</code>924 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">925 <code class="literal">-</code> <em class="replaceable"><code>number</code></em>926 → <code class="returnvalue"><em class="replaceable"><code>number</code></em></code>927 </p>928 <p>929 Negation930 </p>931 <p>932 <code class="literal">- 2.0</code>933 → <code class="returnvalue">-2.0</code>934 </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="refsect2" id="PGBENCH-BUILTIN-FUNCTIONS"><h3>Built-In Functions</h3><p>935 The functions listed in <a class="xref" href="pgbench.html#PGBENCH-FUNCTIONS" title="Table 295. pgbench Functions">Table 295</a> are built936 into <span class="application">pgbench</span> and may be used in expressions appearing in937 <a class="link" href="pgbench.html#PGBENCH-METACOMMAND-SET"><code class="literal">\set</code></a>.938 </p><div class="table" id="PGBENCH-FUNCTIONS"><p class="title"><strong>Table 295. pgbench Functions</strong></p><div class="table-contents"><table class="table" summary="pgbench Functions" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">939 Function940 </p>941 <p>942 Description943 </p>944 <p>945 Example(s)946 </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">947 <code class="function">abs</code> ( <em class="replaceable"><code>number</code></em> )948 → <code class="returnvalue"></code> same type as input949 </p>950 <p>951 Absolute value952 </p>953 <p>954 <code class="literal">abs(-17)</code>955 → <code class="returnvalue">17</code>956 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">957 <code class="function">debug</code> ( <em class="replaceable"><code>number</code></em> )958 → <code class="returnvalue"></code> same type as input959 </p>960 <p>961 Prints the argument to <span class="systemitem">stderr</span>,962 and returns the argument.963 </p>964 <p>965 <code class="literal">debug(5432.1)</code>966 → <code class="returnvalue">5432.1</code>967 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">968 <code class="function">double</code> ( <em class="replaceable"><code>number</code></em> )969 → <code class="returnvalue">double</code>970 </p>971 <p>972 Casts to double.973 </p>974 <p>975 <code class="literal">double(5432)</code>976 → <code class="returnvalue">5432.0</code>977 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">978 <code class="function">exp</code> ( <em class="replaceable"><code>number</code></em> )979 → <code class="returnvalue">double</code>980 </p>981 <p>982 Exponential (<code class="literal">e</code> raised to the given power)983 </p>984 <p>985 <code class="literal">exp(1.0)</code>986 → <code class="returnvalue">2.718281828459045</code>987 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">988 <code class="function">greatest</code> ( <em class="replaceable"><code>number</code></em> [<span class="optional">, <code class="literal">...</code> </span>] )989 → <code class="returnvalue"></code> <code class="type">double</code> if any argument is double, else <code class="type">integer</code>990 </p>991 <p>992 Selects the largest value among the arguments.993 </p>994 <p>995 <code class="literal">greatest(5, 4, 3, 2)</code>996 → <code class="returnvalue">5</code>997 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">998 <code class="function">hash</code> ( <em class="parameter"><code>value</code></em> [<span class="optional">, <em class="parameter"><code>seed</code></em> </span>] )999 → <code class="returnvalue">integer</code>1000 </p>1001 <p>1002 This is an alias for <code class="function">hash_murmur2</code>.1003 </p>1004 <p>1005 <code class="literal">hash(10, 5432)</code>1006 → <code class="returnvalue">-5817877081768721676</code>1007 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">1008 <code class="function">hash_fnv1a</code> ( <em class="parameter"><code>value</code></em> [<span class="optional">, <em class="parameter"><code>seed</code></em> </span>] )1009 → <code class="returnvalue">integer</code>1010 </p>1011 <p>1012 Computes <a class="ulink" href="https://en.wikipedia.org/wiki/Fowler%E2%80%93Noll%E2%80%93Vo_hash_function" target="_top">FNV-1a hash</a>.1013 </p>1014 <p>1015 <code class="literal">hash_fnv1a(10, 5432)</code>1016 → <code class="returnvalue">-7793829335365542153</code>1017 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">1018 <code class="function">hash_murmur2</code> ( <em class="parameter"><code>value</code></em> [<span class="optional">, <em class="parameter"><code>seed</code></em> </span>] )1019 → <code class="returnvalue">integer</code>1020 </p>1021 <p>1022 Computes <a class="ulink" href="https://en.wikipedia.org/wiki/MurmurHash" target="_top">MurmurHash2 hash</a>.1023 </p>1024 <p>1025 <code class="literal">hash_murmur2(10, 5432)</code>1026 → <code class="returnvalue">-5817877081768721676</code>1027 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">1028 <code class="function">int</code> ( <em class="replaceable"><code>number</code></em> )1029 → <code class="returnvalue">integer</code>1030 </p>1031 <p>1032 Casts to integer.1033 </p>1034 <p>1035 <code class="literal">int(5.4 + 3.8)</code>1036 → <code class="returnvalue">9</code>1037 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">1038 <code class="function">least</code> ( <em class="replaceable"><code>number</code></em> [<span class="optional">, <code class="literal">...</code> </span>] )1039 → <code class="returnvalue"></code> <code class="type">double</code> if any argument is double, else <code class="type">integer</code>1040 </p>1041 <p>1042 Selects the smallest value among the arguments.1043 </p>1044 <p>1045 <code class="literal">least(5, 4, 3, 2.1)</code>1046 → <code class="returnvalue">2.1</code>1047 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">1048 <code class="function">ln</code> ( <em class="replaceable"><code>number</code></em> )1049 → <code class="returnvalue">double</code>1050 </p>1051 <p>1052 Natural logarithm1053 </p>1054 <p>1055 <code class="literal">ln(2.718281828459045)</code>1056 → <code class="returnvalue">1.0</code>1057 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">1058<code class="function">mod</code> ( <em class="replaceable"><code>integer</code></em>, <em class="replaceable"><code>integer</code></em> )1059 → <code class="returnvalue">integer</code>1060 </p>1061 <p>1062 Modulo (remainder)1063 </p>1064 <p>1065 <code class="literal">mod(54, 32)</code>1066 → <code class="returnvalue">22</code>1067 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">1068 <code class="function">permute</code> ( <em class="parameter"><code>i</code></em>, <em class="parameter"><code>size</code></em> [, <em class="parameter"><code>seed</code></em> ] )1069 → <code class="returnvalue">integer</code>1070 </p>1071 <p>1072 Permuted value of <em class="parameter"><code>i</code></em>, in the range1073 <code class="literal">[0, size)</code>. This is the new position of1074 <em class="parameter"><code>i</code></em> (modulo <em class="parameter"><code>size</code></em>) in a1075 pseudorandom permutation of the integers <code class="literal">0...size-1</code>,1076 parameterized by <em class="parameter"><code>seed</code></em>, see below.1077 </p>1078 <p>1079 <code class="literal">permute(0, 4)</code>1080 → <code class="returnvalue">an integer between 0 and 3</code>1081 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">1082 <code class="function">pi</code> ()1083 → <code class="returnvalue">double</code>1084 </p>1085 <p>1086 Approximate value of <span class="symbol_font">π</span>1087 </p>1088 <p>1089 <code class="literal">pi()</code>1090 → <code class="returnvalue">3.14159265358979323846</code>1091 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">1092 <code class="function">pow</code> ( <em class="parameter"><code>x</code></em>, <em class="parameter"><code>y</code></em> )1093 → <code class="returnvalue">double</code>1094 </p>1095 <p class="func_signature">1096 <code class="function">power</code> ( <em class="parameter"><code>x</code></em>, <em class="parameter"><code>y</code></em> )1097 → <code class="returnvalue">double</code>1098 </p>1099 <p>1100 <em class="parameter"><code>x</code></em> raised to the power of <em class="parameter"><code>y</code></em>1101 </p>1102 <p>1103 <code class="literal">pow(2.0, 10)</code>1104 → <code class="returnvalue">1024.0</code>1105 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">1106 <code class="function">random</code> ( <em class="parameter"><code>lb</code></em>, <em class="parameter"><code>ub</code></em> )1107 → <code class="returnvalue">integer</code>1108 </p>1109 <p>1110 Computes a uniformly-distributed random integer in <code class="literal">[lb,1111 ub]</code>.1112 </p>1113 <p>1114 <code class="literal">random(1, 10)</code>1115 → <code class="returnvalue">an integer between 1 and 10</code>1116 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">1117 <code class="function">random_exponential</code> ( <em class="parameter"><code>lb</code></em>, <em class="parameter"><code>ub</code></em>, <em class="parameter"><code>parameter</code></em> )1118 → <code class="returnvalue">integer</code>1119 </p>1120 <p>1121 Computes an exponentially-distributed random integer in <code class="literal">[lb,1122 ub]</code>, see below.1123 </p>1124 <p>1125 <code class="literal">random_exponential(1, 10, 3.0)</code>1126 → <code class="returnvalue">an integer between 1 and 10</code>1127 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">1128 <code class="function">random_gaussian</code> ( <em class="parameter"><code>lb</code></em>, <em class="parameter"><code>ub</code></em>, <em class="parameter"><code>parameter</code></em> )1129 → <code class="returnvalue">integer</code>1130 </p>1131 <p>1132 Computes a Gaussian-distributed random integer in <code class="literal">[lb,1133 ub]</code>, see below.1134 </p>1135 <p>1136 <code class="literal">random_gaussian(1, 10, 2.5)</code>1137 → <code class="returnvalue">an integer between 1 and 10</code>1138 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">1139 <code class="function">random_zipfian</code> ( <em class="parameter"><code>lb</code></em>, <em class="parameter"><code>ub</code></em>, <em class="parameter"><code>parameter</code></em> )1140 → <code class="returnvalue">integer</code>1141 </p>1142 <p>1143 Computes a Zipfian-distributed random integer in <code class="literal">[lb,1144 ub]</code>, see below.1145 </p>1146 <p>1147 <code class="literal">random_zipfian(1, 10, 1.5)</code>1148 → <code class="returnvalue">an integer between 1 and 10</code>1149 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">1150 <code class="function">sqrt</code> ( <em class="replaceable"><code>number</code></em> )1151 → <code class="returnvalue">double</code>1152 </p>1153 <p>1154 Square root1155 </p>1156 <p>1157 <code class="literal">sqrt(2.0)</code>1158 → <code class="returnvalue">1.414213562</code>1159 </p></td></tr></tbody></table></div></div><br class="table-break" /><p>1160 The <code class="literal">random</code> function generates values using a uniform1161 distribution, that is all the values are drawn within the specified1162 range with equal probability. The <code class="literal">random_exponential</code>,1163 <code class="literal">random_gaussian</code> and <code class="literal">random_zipfian</code>1164 functions require an additional double parameter which determines the precise1165 shape of the distribution.1166 </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>1167 For an exponential distribution, <em class="replaceable"><code>parameter</code></em>1168 controls the distribution by truncating a quickly-decreasing1169 exponential distribution at <em class="replaceable"><code>parameter</code></em>, and then1170 projecting onto integers between the bounds.1171 To be precise, with1172</p><div class="literallayout"><p><br />1173f(x) = exp(-parameter * (x - min) / (max - min + 1)) / (1 - exp(-parameter))<br />1174</p></div><p>1175 Then value <em class="replaceable"><code>i</code></em> between <em class="replaceable"><code>min</code></em> and1176 <em class="replaceable"><code>max</code></em> inclusive is drawn with probability:1177 <code class="literal">f(i) - f(i + 1)</code>.1178 </p><p>1179 Intuitively, the larger the <em class="replaceable"><code>parameter</code></em>, the more1180 frequently values close to <em class="replaceable"><code>min</code></em> are accessed, and the1181 less frequently values close to <em class="replaceable"><code>max</code></em> are accessed.1182 The closer to 0 <em class="replaceable"><code>parameter</code></em> is, the flatter (more1183 uniform) the access distribution.1184 A crude approximation of the distribution is that the most frequent 1%1185 values in the range, close to <em class="replaceable"><code>min</code></em>, are drawn1186 <em class="replaceable"><code>parameter</code></em>% of the time.1187 The <em class="replaceable"><code>parameter</code></em> value must be strictly positive.1188 </p></li><li class="listitem"><p>1189 For a Gaussian distribution, the interval is mapped onto a standard1190 normal distribution (the classical bell-shaped Gaussian curve) truncated1191 at <code class="literal">-parameter</code> on the left and <code class="literal">+parameter</code>1192 on the right.1193 Values in the middle of the interval are more likely to be drawn.1194 To be precise, if <code class="literal">PHI(x)</code> is the cumulative distribution1195 function of the standard normal distribution, with mean <code class="literal">mu</code>1196 defined as <code class="literal">(max + min) / 2.0</code>, with1197</p><div class="literallayout"><p><br />1198f(x) = PHI(2.0 * parameter * (x - mu) / (max - min + 1)) /<br />1199 (2.0 * PHI(parameter) - 1)<br />1200</p></div><p>