Team Ai
Datasetpublic

codekingpro/portable-devtools

sourceHugging Faceupdated 5mo agoView on Hugging Face
1likes15kdownloads
pgbench.html1731 linesDownload Raw Back to html
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: &lt;builtin: TPC-B (sort of)&gt;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 &lt;&gt; 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">&lt;&gt;</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 &lt;&gt; 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">&lt;</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 &lt; 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">&lt;=</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 &lt;= 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">&gt;</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 &gt; 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">&gt;=</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 &gt;= 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">&amp;</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 &amp; 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">&lt;&lt;</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 &lt;&lt; 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">&gt;&gt;</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 &gt;&gt; 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>

Showing the first 1,200 of 1731 lines. Download the file for the rest.

codekingpro/portable-devtools · Team Ai