Space and Time
Learn/Parameterized Queries

Parameterized Queries

Write one query plan, use it with different values at runtime. The SQL structure stays the same — only the inputs change.

What Are Parameterized Queries?

Think of parameterized queries like a function with arguments — the query plan is the function, and parameters are the arguments. You define the SQL structure once with placeholders, and swap in different values each time you call it.

Static query (hardcoded)

sql
SELECT * FROM ETHEREUM.CONTRACTS
WHERE CONTRACT_CREATOR_ADDRESS =
  0xabc123...

Parameterized query

sql
SELECT * FROM ETHEREUM.CONTRACTS
WHERE CONTRACT_CREATOR_ADDRESS =
  $1

How placeholders work

$1, $2, etc. are replaced with actual values at runtime. The query plan is generated once from the parameterized SQL and reused with any set of parameter values.

Parameters make a single deployed contract work for many different inputs. Here are the most common use cases:

1. Filter by caller's wallet address

sql
-- Show contracts created by a specific address
SELECT * FROM ETHEREUM.CONTRACTS
WHERE CONTRACT_CREATOR_ADDRESS = $1

$1 is a VarBinary — pass any wallet address at runtime.

2. Date range queries

sql
-- Blocks within a time window
SELECT BLOCK_NUMBER, TIME_STAMP
FROM ETHEREUM.BLOCKS
WHERE TIME_STAMP > $1 AND TIME_STAMP < $2

$1 and $2 are Timestamps — Unix milliseconds.

3. Dynamic thresholds

sql
-- Balances above a minimum
SELECT HOLDER, BALANCE
FROM NAMESPACE.BALANCES
WHERE BALANCE > $1

$1 is a BigInt — any integer threshold.

One contract, many users: Generate the query plan once, deploy one contract, and every caller can supply their own parameter values. No redeployment needed.

Start Building

Try parameterized queries in the workbench or follow the deploy tutorial to put them onchain.