Argument Expression Examples#

These expressions are used in the args: list of a run query. Each entry in args: generates a value that is bound to a query parameter ($1, $2, etc.).

Aggregation#

Batch operations#

The recommended approach for batch inserts is exec_batch or query_batch with __values__:

seed {
  populate_users(count: 1000, size: 100)
    `INSERT INTO users (email)
    __values__` (
    gen('email')
  )
}

seed:
  - name: populate_users
    type: exec_batch
    count: 1000
    size: 100
    args:
      - gen('email')
    query: |-
      INSERT INTO users (email)
      __values__

For Oracle, use the parameterized form __values__(table(cols)) to generate INSERT ALL ... SELECT 1 FROM DUAL.

The following expressions are used with the driver-specific batch expansion patterns (unnest, JSON_TABLE, etc.):

When using driver-specific batch expansion, always use __sep__ instead of a literal comma delimiter. Generated values (names, addresses, etc.) can contain commas, which would silently split a single value into multiple rows and corrupt your data. The __values__ approach avoids this issue entirely.

Binary#

Conditionals & dependent columns#

Constants & globals#

Dates & times#

Geographic#

Hierarchical (ltree)#

Invalid ltree characters (hyphens, spaces, etc.) are automatically replaced with underscores. Nil and empty parts are skipped.

Identifiers#

JSON & arrays#

Network#

Correlated totals#

Numeric distributions#

PII & locale#

Supported locales: en_US, ja_JP, de_DE, fr_FR, es_ES, pt_BR, zh_CN, ko_KR. Aliases like ja, de, fr also work.

Random values#

Reference data#

Random selection#

Distribution-based selection#

Iteration & pagination#

Multi-value selection#

Populating child tables from parent tables#

When seeding a child table (e.g. account) from every row in a parent table (e.g. customer), use ref_each or ref_cursor instead of manual LIMIT/OFFSET pagination.

ref_each - load all parent rows, iterate in batches#

ref_each('SQL') runs the SQL query, loads all returned rows into memory, then executes the parent query once per row. Combined with __values__, rows are collapsed into multi-row INSERTs controlled by size.

Best for small-to-medium parent tables (under ~1M rows) where loading all IDs into memory is acceptable.

seed {
  populate_customer(type: exec_batch, count: customers, size: batch_size, workers: 4)
    `INSERT INTO customer (email)
    __values__` (gen('email'))

  populate_account(size: batch_size, workers: 4)
    `INSERT INTO account (balance, customer_id)
    __values__` (
      initial_balance,
      ref_each('SELECT id FROM customer').id
  )
}

seed:
  - name: populate_customer
    type: exec_batch
    count: customers
    size: batch_size
    workers: 4
    args:
      - gen('email')
    query: |-
      INSERT INTO customer (email)
      __values__

  - name: populate_account
    size: batch_size
    workers: 4
    args:
      - initial_balance
      - ref_each('SELECT id FROM customer').id
    query: |-
      INSERT INTO account (balance, customer_id)
      __values__

ref_cursor - keyset-paginated streaming#

ref_cursor('SQL', page_size, 'cursor_column') pages through the parent table using keyset pagination (WHERE cursor_col > $last_value ORDER BY cursor_col LIMIT page_size). Only one page of rows is in memory at a time.

Best for large parent tables (1M+ rows) where loading all IDs into memory is impractical.

seed {
  populate_customer(type: exec_batch, count: customers, size: batch_size, workers: 4)
    `INSERT INTO customer (email)
    __values__` (gen('email'))

  populate_account(size: batch_size, workers: 4)
    `INSERT INTO account (balance, customer_id)
    __values__` (
      initial_balance,
      ref_cursor('SELECT id FROM customer ORDER BY id', batch_size, 'id')
  )
}

seed:
  - name: populate_customer
    type: exec_batch
    count: customers
    size: batch_size
    workers: 4
    args:
      - gen('email')
    query: |-
      INSERT INTO customer (email)
      __values__

  - name: populate_account
    size: batch_size
    workers: 4
    args:
      - initial_balance
      - ref_cursor('SELECT id FROM customer ORDER BY id', batch_size, 'id')
    query: |-
      INSERT INTO account (balance, customer_id)
      __values__

Set distributions#

Strings & formatting#

Vectors#

Synthetic (no API required)#

Real embeddings (requires --embed-api-key)#

Non-batched (exec/query)#

Each embed() call makes a separate API request:

insert_product(type: exec)
  `INSERT INTO product (name, description, embedding)
  VALUES ($1, $2, $3::VECTOR)` (
  ref_same('product_catalog').name,
  ref_same('product_catalog').description,
  embed(ref_same('product_catalog').name, ref_same('product_catalog').description)
)

- name: insert_product
  type: exec
  args:
    - ref_same('product_catalog').name
    - ref_same('product_catalog').description
    - embed(ref_same('product_catalog').name, ref_same('product_catalog').description)
  query: |-
    INSERT INTO product (name, description, embedding)
    VALUES ($1, $2, $3::VECTOR)

With 100 iterations, this makes 100 API calls (one per row).

Batched (exec_batch/query_batch)#

In batch queries, embed() calls are deferred - placeholders are inserted during arg evaluation, then all pending texts are resolved together at the end of each batch:

populate_product(count: 100, size: 50)
  `INSERT INTO product (name, description, embedding)
  SELECT n, d, e::VECTOR
  FROM unnest(ARRAY[$1], ARRAY[$2], ARRAY[$3]) AS t(n, d, e)` (
  ref_each(product_catalog).name,
  ref_each(product_catalog).description,
  embed(ref_each(product_catalog).name, ref_each(product_catalog).description)
)

- name: populate_product
  type: exec_batch
  count: 100
  size: 50
  args:
    - ref_each(product_catalog).name
    - ref_each(product_catalog).description
    - embed(ref_each(product_catalog).name, ref_each(product_catalog).description)
  query: |-
    INSERT INTO product (name, description, embedding)
    SELECT n, d, e::VECTOR
    FROM unnest(ARRAY[$1], ARRAY[$2], ARRAY[$3]) AS t(n, d, e)

With count: 100 and size: 50, there are 2 batches of 50. Each batch collects 50 texts, then resolves them in a single API call - 2 API calls instead of 100.

Use --embed-max-batch to cap texts per API call. For example, --embed-max-batch 30 on a 50-row batch produces 2 API calls (30+20) per batch, or 4 total (30+20+30+20).