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.).

Looking for function signatures and return types? See the Function Reference.

Aggregation#

Batch#

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')
  )
}

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#

Constants & variables#

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.

Generation#

Uniqueness#

uniq() state resets between queries, so two seed queries using uniq("gen('email')") can produce duplicates. Use uniq_across() when values must be unique across multiple queries (e.g. unique email across users and admins tables). The pool persists for the lifetime of the environment.

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
  )
}

ref_each with exact cardinality#

ref_each(dataset, N) gives each parent row exactly N children. Pass the repeat count as the second argument and set count to count('parent') * N.

ref customers [
  {id: 1, name: "Alice"},
  {id: 2, name: "Bob"},
  {id: 3, name: "Carol"}
]

seed {
  populate_orders(type: exec_batch, count: count('customers') * 3, size: 100)
    `INSERT INTO orders (id, customer_id, amount)
    __values__` (
      uuid(),
      ref_each(customers, 3).id,
      rand_f(10.0, 500.0)
    )
}

Each customer gets exactly 3 orders (9 total). edg doctor warns if count doesn’t match dataset_size × repeat.

ref_each with N across two tables#

Combine two ref_each datasets to build a cross-product with controlled cardinality. Each warehouse gets exactly 2 inventory rows per product (6 rows per warehouse, 12 total).

ref warehouses [
  {id: 1, name: "East"},
  {id: 2, name: "West"}
]

ref products [
  {id: 10, sku: "BOLT"},
  {id: 20, sku: "NUT"},
  {id: 30, sku: "WASHER"}
]

seed {
  populate_inventory(type: exec_batch, count: count('warehouses') * count('products') * 2, size: 100)
    `INSERT INTO inventory (warehouse_id, product_id, quantity)
    __values__` (
      ref_each(warehouses, count('products') * 2).id,
      ref_each(products, 2).id,
      rand_i(0, 500)
    )
}

Output pattern (12 rows):

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')
  )
}

ref_cursor with exact cardinality#

ref_cursor('SQL', page_size, 'cursor_col', N) combines keyset pagination with repeat count. Each parent row is returned N times before advancing. Memory stays constant - only one page in memory at a time, same as without repeat.

Best for large parent tables (1M+ rows) where ref_each(query, N) would exhaust memory.

seed {
  populate_customer(type: exec_batch, count: 1000000, 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', 3)
  )
}

Each customer gets exactly 3 accounts (3M total). Pages stream 1 batch at a time - no matter how many customers exist.

Set selection#

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)
)

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)
)

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).

User-defined expressions#

The expr declaration defines named functions from expr-lang expression strings. Each expression becomes a callable function available in any query arg. Expressions can reference globals, built-in functions, and other expressions. Arguments are available via the args slice.

let total_rows = 10000
let num_buckets = 10

expr rows_per_bucket = total_rows / num_buckets
expr ten_percent = int(ceil(total_rows * 0.1))

expr clamp = max(min(args[0], args[1]), 0)
expr pct_of = int(ceil(args[0] * args[1] / 100))
expr like_prefix = string(args[0]) + '%'
expr pick_label = args[0] > 1000 ? 'large' : 'small'
expr wrapped_offset = abs(args[0] - args[1]) % args[2]
expr power_scale = int(floor(float(args[0]) ** 2))
expr is_active = not (args[0] == 0) and (args[0] != args[1] or args[0] < args[2])
expr safe_val = args[0] ?? args[1]
expr round_ratio = round(float(args[0]) / float(args[1]))
expr normalize = lower(trim(replace(args[0], ' ', '_')))
expr shout = upper(split(args[0], ',')[0])
expr add_piped = (args[0] + args[1]) | int

run {
  example_query `SELECT * FROM t WHERE bucket = $1 AND label = $2 AND name LIKE $3 AND score >= $4 AND active = $5 AND tag = $6 AND rank >= $7 AND tier = $8 AND fallback = $9 AND weight = $10 AND grp = $11 AND max_id <= $12 LIMIT $13 OFFSET $14` (
    gen('number:1,' + num_buckets),
    pick_label(total_rows),
    like_prefix('foo'),
    pct_of(total_rows, 5),
    is_active(1, 2, 100),
    normalize(' Foo Bar '),
    power_scale(3),
    shout('hello,world'),
    safe_val('premium', 'basic'),
    round_ratio(total_rows, num_buckets),
    wrapped_offset(7, 20, num_buckets),
    add_piped(rows_per_bucket, ten_percent),
    clamp(rows_per_bucket, 500),
    ten_percent,
  )
}