Advanced Log Querying and Filtering

The Logs Explorer exposes logs from each part of the Supabase stack, which you can query and filter using SQL.

You can access the following log sources from the Sources drop-down:

• auth_logs: GoTrue server logs, containing authentication/authorization activity.
• edge_logs: Edge network logs, containing request and response metadata retrieved from Cloudflare.
• function_edge_logs: Edge network logs for only edge functions, containing network requests and response metadata for each execution.
• function_logs: Function internal logs, containing any console logging from within the edge function.
• postgres_logs: Postgres database logs, containing statements executed by connected applications.
• realtime_logs: Realtime server logs, containing client connection information.
• storage_logs: Storage server logs, containing object upload and retrieval information.

The Logs Explorer runs on ClickHouse. Every log line from every source is one row in a single logs table, tagged by a source column. Structured fields live in a log_attributes map, and the raw line is in event_message. Filter by source to scope a query to one service.

Timestamp display and behavior#

The timestamp column is a DateTime64 value in UTC, formatted as an ISO-8601 string like 2026-06-22T09:34:06.215000. You can order and compare it directly, so no conversion function is needed. In the Logs Explorer the selected time range is applied for you, so you rarely need to filter on timestamp by hand.

1
select timestamp, event_message
2
from logs
3
where source = 'edge_logs'
4
order by timestamp desc
5
limit 100;

Reading fields from log_attributes#

Structured fields live in the log_attributes map. Read a field with bracket access, keeping the full dotted key. There are no unnesting joins.

1
select
2
  log_attributes['request.method'] as method,
3
  log_attributes['request.path'] as path,
4
  log_attributes['response.status_code'] as status
5
from logs
6
where source = 'edge_logs'
7
limit 100;

The key keeps the full dotted path, with the metadata root dropped. What BigQuery expressed as metadata.request.cf.country is log_attributes['request.cf.country']. Keep the full prefix rather than shortening it.

Map values are always strings. To compare or aggregate a numeric field, wrap it in toInt32OrZero, which returns 0 for a missing or non-numeric value:

1
select count() as server_errors
2
from logs
3
where source = 'edge_logs'
4
  and toInt32OrZero(log_attributes['response.status_code']) between 500 and 599;

Do not guess keys. Discover the keys a source sets from recent rows:

1
select arrayJoin(mapKeys(log_attributes)) as key, count() as n
2
from logs
3
where source = 'postgres_logs'
4
group by key
5
order by n desc
6
limit 100;

LIMIT and result row limitations#

The Logs Explorer has a maximum of 1000 rows per run. Use LIMIT to reduce the number of rows returned further.

Best practices#

1. Use a narrow time range.

The Logs Explorer applies the time range you select, so keep it tight. Querying a very large range risks timeouts, especially for Enterprise customers with long retention, because of the extra data scanned.

2. Select only the fields you need.

Selecting the whole log_attributes map, or every column, reads far more data than you need and slows the query down. Select the specific keys instead.

1
-- ❌ Avoid this: selecting the whole attributes map
2
select timestamp, log_attributes
3
from logs
4
where source = 'edge_logs';
5
6
-- ✅ Do this: select only the keys you need
7
select timestamp, log_attributes['request.method'] as method
8
from logs
9
where source = 'edge_logs';

Examples and templates#

The Logs Explorer includes Templates (available in the Templates tab or the dropdown in the Query tab) to help you get started.

For example, you can enter the following query in the SQL Editor to retrieve each user's IP address:

1
select timestamp, log_attributes['request.headers.x_real_ip'] as x_real_ip
2
from logs
3
where source = 'edge_logs'
4
  and log_attributes['request.headers.x_real_ip'] != ''
5
  and log_attributes['request.method'] = 'GET'
6
order by timestamp desc
7
limit 100;

Understanding field references#

Every log source shares the same logs table. Each row has these columns:

Service-specific details live in log_attributes. For example, in postgres_logs the log_attributes['parsed.error_severity'] field holds the error level of an event. Read those fields with bracket access:

1
select
2
  event_message,
3
  log_attributes['parsed.error_severity'] as error_severity,
4
  log_attributes['parsed.user_name'] as user_name
5
from logs
6
where source = 'postgres_logs'
7
limit 100;

Expanding results#

Logs returned by queries may be difficult to read in table format. Double-click a row to expand the result into more readable JSON:

Filtering with regular expressions#

Use the ClickHouse match function for regular expressions. In its most basic form, it checks whether a pattern is present in a column.

1
select timestamp, event_message
2
from logs
3
where source = 'postgres_logs'
4
  and match(event_message, 'is present')
5
limit 100;

There are multiple operators to consider using.

Find messages that start with a phrase#

^ only looks for values at the start of a string

1
-- find only messages that start with connection
2
match(event_message, '^connection')

Find messages that end with a phrase#

$ only looks for values at the end of the string

1
-- find only messages that end with port=12345
2
match(event_message, 'port=12345$')

Ignore case sensitivity#

(?i) ignores capitalization for all proceeding characters

1
-- find all event_messages with the word "connection"
2
match(event_message, '(?i)COnnecTion')

For a plain case-insensitive substring match, ilike is simpler:

1
-- find all event_messages containing "connection", in any case
2
event_message ilike '%connection%'

Wildcards#

. matches any single character, and .* matches any sequence of characters

1
-- find event_messages like "hello<anything>world"
2
match(event_message, 'hello.*world')

Alphanumeric ranges#

[0-9a-zA-Z] matches a single alphanumeric character. Anchor it with ^[0-9a-zA-Z]+$ to match a value that is entirely alphanumeric.

1
-- find event_messages that contain a digit between 1 and 5 (inclusive)
2
match(event_message, '[1-5]')

Repeated values#

x* zero or more x x+ one or more x x? zero or one x x{4,} four or more x x{3} exactly 3 x

1
-- find event_messages that contain any sequence of 3 digits
2
match(event_message, '[0-9]{3}')

Escaping reserved characters#

\. is interpreted as a period . instead of as a wildcard

1
-- escapes .
2
match(event_message, 'hello world\.')

or statements#

x|y any string with x or y present

1
-- find event_messages that have the word 'started' followed by either "host" or "authenticated"
2
match(event_message, 'started (host|authenticated)')

and/or/not statements in SQL#

and, or, and not are native terms in SQL and can be used with regular expressions to filter results

1
select timestamp, event_message
2
from logs
3
where source = 'postgres_logs'
4
  and (
5
    (match(event_message, 'connection') and match(event_message, 'host'))
6
    or not match(event_message, 'received')
7
  )
8
limit 100;

Filtering example#

Filter for Postgres errors:

1
select
2
  timestamp,
3
  log_attributes['parsed.error_severity'] as error_severity,
4
  log_attributes['parsed.user_name'] as user_name,
5
  event_message
6
from logs
7
where source = 'postgres_logs'
8
  and match(log_attributes['parsed.error_severity'], 'ERROR|FATAL|PANIC')
9
order by timestamp desc
10
limit 100;

Limitations#

The wildcard operator * is not supported#

The logs query surface rejects select * and count(*). List the columns you need, and use count() for row counts:

1
select timestamp, event_message, log_attributes['parsed.error_severity'] as error_severity
2
from logs
3
where source = 'postgres_logs'
4
order by timestamp desc
5
limit 100;