get_logs table function

Example

Live RPC

-- Recent finalized-window USDC Transfer aggregation
WITH head AS (
  SELECT number AS head_block
  FROM get_block($client, 'finalized')
),
transfers AS (
  SELECT
    "to",
    value
  FROM head,
  get_logs(
    $client,
    '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48'::ADDRESS, -- Ethereum mainnet USDC
    'event Transfer(address indexed from, address indexed to, uint256 value)',
    head_block - 5,
    head_block
  )
)
SELECT
  "to",
  sum(value) AS raw_value,
  format_units(sum(value), 6) AS usdc_value
FROM transfers
GROUP BY "to"
ORDER BY raw_value DESC;

Enable JavaScript to run this sample in the notebook. The SQL preview above is still available for reference.

API reference

get_logs(CLIENT, ADDRESS | ADDRESS[], VARCHAR | JSON) # RPC required

Read stored logs without bounds using a retained execution CLIENT; live and pinned clients require both bounds. A failed RPC request raises.

Exact signatures (4)

get_logs(CLIENT, ADDRESS, VARCHAR)
get_logs(CLIENT, ADDRESS, JSON)
get_logs(CLIENT, ADDRESS[], VARCHAR)
get_logs(CLIENT, ADDRESS[], JSON)

Inputs

Name	Type	Use
`client`	CLIENT Attached live CLIENT for RPC logs, attached pinned CLIENT with both block bounds, or retained execution CLIENT without block bounds. Retained execution reads do not require an attached TRANSPORT; detached pinned clients are rejected.	required positional
`address`	ADDRESS \| ADDRESS[] ADDRESS, NULL::ADDRESS for no emitter filter, or ADDRESS[]. A NULL or empty ADDRESS[] reads no logs. RPC address lists are de-duplicated and split into requests of at most 50 addresses.	required positional
`event_signature / event_abi`	VARCHAR \| JSON VARCHAR: Event declaration used for topic0 filtering and decoding. It must be foldable to add decoded output columns. JSON: JSON event fragment used for topic0 filtering and decoding. It must be foldable to add decoded output columns.	required positional
`topic0`	BYTES32 or list Exact value or OR-list at topic position 0. For RPC requests it replaces the event-derived selector; only logs of the declared event decode, and retained execution logs must also match the event selector.	optional named
`topic3`	BYTES32 or list Exact value or OR-list for the third indexed parameter; a constant or a column read per row.	optional named
`topic1`	BYTES32 or list Exact value or OR-list for the first indexed parameter; a constant or a column read per row.	optional named
`topic2`	BYTES32 or list Exact value or OR-list for the second indexed parameter; a constant or a column read per row.	optional named

Result columns

Name	Type
`address`	ADDRESS Log emitter.
`block_hash`	BYTES32 Containing block hash.
`block_number`	BLOCK_NUMBER Containing block height.
`block_timestamp`	TIMESTAMP Containing block time in UTC, from the provider's log, or the block header when the log lacks it.
`transaction_hash`	BYTES32 Emitting transaction hash.

get_logs(CLIENT, ADDRESS | ADDRESS[], VARCHAR | JSON, BIGINT) # RPC required

Read logs from an inclusive lower bound to the head; the host refuses it on a live CLIENT, pinned clients require both bounds and retained states reject bounds. A failed RPC request raises.

Exact signatures (4)

get_logs(CLIENT, ADDRESS, VARCHAR, BIGINT)
get_logs(CLIENT, ADDRESS, JSON, BIGINT)
get_logs(CLIENT, ADDRESS[], VARCHAR, BIGINT)
get_logs(CLIENT, ADDRESS[], JSON, BIGINT)

Inputs

Name	Type	Use
`client`	CLIENT Attached live CLIENT for RPC logs, attached pinned CLIENT with both block bounds, or retained execution CLIENT without block bounds. Retained execution reads do not require an attached TRANSPORT; detached pinned clients are rejected.	requiredpositional
`address`	ADDRESS \| ADDRESS[] ADDRESS, NULL::ADDRESS for no emitter filter, or ADDRESS[]. A NULL or empty ADDRESS[] reads no logs. RPC address lists are de-duplicated and split into requests of at most 50 addresses.	requiredpositional
`event_signature / event_abi`	VARCHAR \| JSON VARCHAR: Event declaration used for topic0 filtering and decoding. It must be foldable to add decoded output columns. JSON: JSON event fragment used for topic0 filtering and decoding. It must be foldable to add decoded output columns.	requiredpositional
`from_block`	BIGINT Inclusive first block.	requiredpositional
`topic0`	BYTES32 or list Exact value or OR-list at topic position 0. For RPC requests it replaces the event-derived selector; only logs of the declared event decode, and retained execution logs must also match the event selector.	optionalnamed

Result columns

Name	Type
`address`	ADDRESS Log emitter.
`block_hash`	BYTES32 Containing block hash.
`block_number`	BLOCK_NUMBER Containing block height.
`block_timestamp`	TIMESTAMP Containing block time in UTC, from the provider's log, or the block header when the log lacks it.
`transaction_hash`	BYTES32 Emitting transaction hash.

get_logs(CLIENT, ADDRESS | ADDRESS[], VARCHAR | JSON, BIGINT, BIGINT) # RPC required

Read an inclusive range using a live or attached pinned CLIENT. A NULL bound, or from_block after to_block, raises. Chunks start at 2000 blocks and double while sparse, up to max_block_range; retryable failures retry five times, then raise. Topics are BYTES32 or ADDRESS words or lists, constant or per row; NULL or empty raises. An empty ADDRESS[] reads nothing. Logs carry block_timestamp.

Exact signatures (4)

get_logs(CLIENT, ADDRESS, VARCHAR, BIGINT, BIGINT)
get_logs(CLIENT, ADDRESS, JSON, BIGINT, BIGINT)
get_logs(CLIENT, ADDRESS[], VARCHAR, BIGINT, BIGINT)
get_logs(CLIENT, ADDRESS[], JSON, BIGINT, BIGINT)

Inputs

Name	Type	Use
`client`	CLIENT Attached live CLIENT for RPC logs, attached pinned CLIENT with both block bounds, or retained execution CLIENT without block bounds. Retained execution reads do not require an attached TRANSPORT; detached pinned clients are rejected.	requiredpositional
`address`	ADDRESS \| ADDRESS[] ADDRESS, NULL::ADDRESS for no emitter filter, or ADDRESS[]. A NULL or empty ADDRESS[] reads no logs. RPC address lists are de-duplicated and split into requests of at most 50 addresses.	requiredpositional
`event_signature / event_abi`	VARCHAR \| JSON VARCHAR: Event declaration used for topic0 filtering and decoding. It must be foldable to add decoded output columns. JSON: JSON event fragment used for topic0 filtering and decoding. It must be foldable to add decoded output columns.	requiredpositional
`from_block`	BIGINT Inclusive first block.	requiredpositional
`to_block`	BIGINT Inclusive last block.	requiredpositional

Result columns

Name	Type
`address`	ADDRESS Log emitter.
`block_hash`	BYTES32 Containing block hash.
`block_number`	BLOCK_NUMBER Containing block height.
`block_timestamp`	TIMESTAMP Containing block time in UTC, from the provider's log, or the block header when the log lacks it.
`transaction_hash`	BYTES32 Emitting transaction hash.

Guidance

Request construction

from_block and to_block are inclusive. With both bounds, get_logs reads the range in chunks: the first spans 2000 blocks (or the CLIENT's max_block_range when smaller), and a chunk with fewer than 5000 logs doubles the next, up to max_block_range. A provider's range limit fixes the chunk for the rest of the read.

A NULL from_block or to_block raises; it never reads without bounds. from_block after to_block raises.

block_timestamp comes with each log from the provider, so a log's time needs no header read; a log without it (or with 0x0) takes its block header's, one batched read per such block.

RPC ADDRESS[] values are split into requests of at most 50 addresses.
Pinned clients require both from_block and to_block. Retained execution clients reject either bound.

Failure handling

A request with both bounds retries retryable failures up to five times per chunk, then raises an error. A non-retryable provider failure raises immediately.

A request without both bounds that fails raises; an empty result always means no matching logs.

A log that is not the declared event keeps its row with NULL decoded columns: its topic0 differs, its topic count is not one plus the indexed inputs, or its data does not decode. ERC-20 and ERC-721 Transfer share topic0, and an ERC-721 Transfer carries its token id as a fourth topic.

Reproducible and efficient reads

Resolve and persist numeric bounds from a finalized head when later runs must scan the same block window.

SQL LIMIT is applied after logs are fetched. Use emitter, topic, and block filters to reduce RPC work.

Live RPC

-- Recent finalized-window WETH Transfer decoding with a JSON ABI
WITH head AS (
  SELECT number::BIGINT AS head_block
  FROM get_block($client, 'finalized')
)
SELECT transaction_hash, log_index, "from", "to", format_units(value, 18) AS weth_amount
FROM head,
get_logs(
  $client,
  '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2'::ADDRESS,
  '{"type":"event","name":"Transfer","inputs":[{"indexed":true,"name":"from","type":"address"},{"indexed":true,"name":"to","type":"address"},{"indexed":false,"name":"value","type":"uint256"}]}'::JSON,
  head_block - 5,
  head_block
);

Enable JavaScript to run this sample in the notebook. The SQL preview above is still available for reference.

Topic matching

Topic filters are ANDed by position. A BYTES32[] value is an OR-list within one position.

For RPC requests, an explicit topic0 replaces the selector derived from a non-anonymous event.

Retained execution logs are decoded only when they match both the event selector and every explicit topic filter, including topic0.

topic1, topic2, and topic3 correspond to the first three indexed event parameters.
A WHERE comparing an indexed event field with a constant (= or IN) is sent to the node as that topic's filter; the WHERE still applies, so only the read narrows.
A topic value is a BYTES32, or an ADDRESS padded as evm_abi_word pads it; encode other values with evm_abi_word. A NULL, an empty list or any other value raises. A topic from a column (LATERAL) is read per row.

Live RPC

WITH head AS (
  SELECT number AS head_block
  FROM get_block($client, 'finalized')
),
transfers AS (
  SELECT
    address,
    value
  FROM head,
  get_logs(
    $client,
    [
      '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
      '0xdAC17F958D2ee523a2206206994597C13D831ec7'
    ]::ADDRESS[],
    'event Transfer(address indexed from, address indexed to, uint256 value)',
    head_block - 5,
    head_block
  )
)
SELECT
  address AS token,
  count(*) AS transfer_count,
  sum(value) AS raw_value,
  format_units(sum(value), 6) AS token_value
FROM transfers
GROUP BY address
ORDER BY address;

Enable JavaScript to run this sample in the notebook. The SQL preview above is still available for reference.

Topic filters

For ERC-20 Transfer(address indexed from, address indexed to, uint256 value), topic0 is the event selector, topic1 is from, and topic2 is to.

Addressless scans require a provider that supports unaddressed eth_getLogs requests.

Build topic0 with event_signature instead of copying a hash.
Build indexed address topics with evm_abi_word instead of manually padding addresses.
Use BYTES32[] for an OR filter.

Example

API reference

Inputs

Result columns

Inputs

Result columns

Inputs

Result columns

Guidance

Request construction

Failure handling

Reproducible and efficient reads

Topic matching

Topic filters

Related functions

Usually used after

Usually used before