Skip to content
Pydantic Docs

Query Client

LogfireQueryClient

Bases: _BaseLogfireQueryClient[Client]

A synchronous client for querying Logfire data.

Methods

info 

def info() -> ReadTokenInfo

Get information about the read token.

Returns

ReadTokenInfo

query_json_rows 

def query_json_rows(
    sql: str,
    min_timestamp: None = None,
    max_timestamp: datetime | None = None,
    limit: int | None = None,
    timezone: str | None = None,
    environment: str | list[str] | None = None,
) -> RowQueryResults
def query_json_rows(
    sql: str,
    min_timestamp: datetime,
    max_timestamp: datetime | None = None,
    limit: int | None = None,
    timezone: str | None = None,
    environment: str | list[str] | None = None,
) -> RowQueryResults

Query Logfire data and return the results as a row-oriented dictionary.

Returns

RowQueryResults — A dictionary with two entries:

  • columns: A list of column details including the name, datatype and whether the column is nullable.
  • rows: The list of rows matching the query.
Parameters

sql : str

The SQL SELECT query to execute.

min_timestamp : datetime | None Default: None

The minimum timestamp to use when querying data. If the provided datetime doesn’t have a timezone set, it is assumed to be UTC.

⚠ Deprecated in v4.35.0

Not providing a min_timestamp is deprecated.

max_timestamp : datetime | None Default: None

The maximum timestamp to use when querying data. If the provided datetime doesn’t have a timezone set, it is assumed to be UTC.

limit : int | None Default: None

The maximum number of rows to query. This value takes priority over the LIMIT clause in the sql query.

timezone : str | None Default: None

The timezone to use for the query execution context.

environment : str | list[str] | None Default: None

Restrict rows to the provided environment(s). To only query rows where no environment is set, use the empty string ('').

query_arrow 

def query_arrow(
    sql: str,
    min_timestamp: None = None,
    max_timestamp: datetime | None = None,
    limit: int | None = None,
    timezone: str | None = None,
    environment: str | list[str] | None = None,
) -> Table
def query_arrow(
    sql: str,
    min_timestamp: datetime,
    max_timestamp: datetime | None = None,
    limit: int | None = None,
    timezone: str | None = None,
    environment: str | list[str] | None = None,
) -> Table

Query Logfire data and return the results as a pyarrow Table.

Note that pyarrow must be installed for this method to succeed.

You can use polars.from_arrow(result) to convert the returned table to a polars DataFrame.

Returns

Table

Parameters

sql : str

The SQL SELECT query to execute.

min_timestamp : datetime | None Default: None

The minimum timestamp to use when querying data. If the provided datetime doesn’t have a timezone set, it is assumed to be UTC.

⚠ Deprecated in v4.35.0

Not providing a min_timestamp is deprecated.

max_timestamp : datetime | None Default: None

The maximum timestamp to use when querying data. If the provided datetime doesn’t have a timezone set, it is assumed to be UTC.

limit : int | None Default: None

The maximum number of rows to query. This value takes priority over the LIMIT clause in the sql query.

timezone : str | None Default: None

The timezone to use for the query execution context.

environment : str | list[str] | None Default: None

Restrict rows to the provided environment(s). To only query rows where no environment is set, use the empty string ('').

query_csv 

def query_csv(
    sql: str,
    min_timestamp: None = None,
    max_timestamp: datetime | None = None,
    limit: int | None = None,
    timezone: str | None = None,
    environment: str | list[str] | None = None,
) -> str
def query_csv(
    sql: str,
    min_timestamp: datetime,
    max_timestamp: datetime | None = None,
    limit: int | None = None,
    timezone: str | None = None,
    environment: str | list[str] | None = None,
) -> str

Query Logfire data and return the results as a CSV-format string.

Use polars.read_csv(StringIO(result)) to convert the returned CSV to a polars DataFrame.

Returns

str

Parameters

sql : str

The SQL SELECT query to execute.

min_timestamp : datetime | None Default: None

The minimum timestamp to use when querying data. If the provided datetime doesn’t have a timezone set, it is assumed to be UTC.

⚠ Deprecated in v4.35.0

Not providing a min_timestamp is deprecated.

max_timestamp : datetime | None Default: None

The maximum timestamp to use when querying data. If the provided datetime doesn’t have a timezone set, it is assumed to be UTC.

limit : int | None Default: None

The maximum number of rows to query. This value takes priority over the LIMIT clause in the sql query.

timezone : str | None Default: None

The timezone to use for the query execution context.

environment : str | list[str] | None Default: None

Restrict rows to the provided environment(s). To only query rows where no environment is set, use the empty string ('').

AsyncLogfireQueryClient

Bases: _BaseLogfireQueryClient[AsyncClient]

An asynchronous client for querying Logfire data.

Methods

info

@async

def info() -> ReadTokenInfo

Get information about the read token.

Returns

ReadTokenInfo

query_json_rows

@async

def query_json_rows(
    sql: str,
    min_timestamp: None = None,
    max_timestamp: datetime | None = None,
    limit: int | None = None,
    timezone: str | None = None,
    environment: str | list[str] | None = None,
) -> RowQueryResults
def query_json_rows(
    sql: str,
    min_timestamp: datetime,
    max_timestamp: datetime | None = None,
    limit: int | None = None,
    timezone: str | None = None,
    environment: str | list[str] | None = None,
) -> RowQueryResults

Query Logfire data and return the results as a row-oriented dictionary.

Returns

RowQueryResults — A dictionary with two entries:

  • columns: A list of column details including the name, datatype and whether the column is nullable.
  • rows: The list of rows matching the query.
Parameters

sql : str

The SQL SELECT query to execute.

min_timestamp : datetime | None Default: None

The minimum timestamp to use when querying data. If the provided datetime doesn’t have a timezone set, it is assumed to be UTC.

⚠ Deprecated in v4.35.0

Not providing a min_timestamp is deprecated.

max_timestamp : datetime | None Default: None

The maximum timestamp to use when querying data. If the provided datetime doesn’t have a timezone set, it is assumed to be UTC.

limit : int | None Default: None

The maximum number of rows to query. This value takes priority over the LIMIT clause in the sql query.

timezone : str | None Default: None

The timezone to use for the query execution context.

environment : str | list[str] | None Default: None

Restrict rows to the provided environment(s). To only query rows where no environment is set, use the empty string ('').

query_arrow

@async

def query_arrow(
    sql: str,
    min_timestamp: None = None,
    max_timestamp: datetime | None = None,
    limit: int | None = None,
    timezone: str | None = None,
    environment: str | list[str] | None = None,
) -> Table
def query_arrow(
    sql: str,
    min_timestamp: datetime,
    max_timestamp: datetime | None = None,
    limit: int | None = None,
    timezone: str | None = None,
    environment: str | list[str] | None = None,
) -> Table

Query Logfire data and return the results as a pyarrow Table.

Note that pyarrow must be installed for this method to succeed.

You can use polars.from_arrow(result) to convert the returned table to a polars DataFrame.

Returns

Table

Parameters

sql : str

The SQL SELECT query to execute.

min_timestamp : datetime | None Default: None

The minimum timestamp to use when querying data. If the provided datetime doesn’t have a timezone set, it is assumed to be UTC.

⚠ Deprecated in v4.35.0

Not providing a min_timestamp is deprecated.

max_timestamp : datetime | None Default: None

The maximum timestamp to use when querying data. If the provided datetime doesn’t have a timezone set, it is assumed to be UTC.

limit : int | None Default: None

The maximum number of rows to query. This value takes priority over the LIMIT clause in the sql query.

timezone : str | None Default: None

The timezone to use for the query execution context.

environment : str | list[str] | None Default: None

Restrict rows to the provided environment(s). To only query rows where no environment is set, use the empty string ('').

query_csv

@async

def query_csv(
    sql: str,
    min_timestamp: None = None,
    max_timestamp: datetime | None = None,
    limit: int | None = None,
    timezone: str | None = None,
    environment: str | list[str] | None = None,
) -> str
def query_csv(
    sql: str,
    min_timestamp: datetime,
    max_timestamp: datetime | None = None,
    limit: int | None = None,
    timezone: str | None = None,
    environment: str | list[str] | None = None,
) -> str

Query Logfire data and return the results as a CSV-format string.

Use polars.read_csv(StringIO(result)) to convert the returned CSV to a polars DataFrame.

Returns

str

Parameters

sql : str

The SQL SELECT query to execute.

min_timestamp : datetime | None Default: None

The minimum timestamp to use when querying data. If the provided datetime doesn’t have a timezone set, it is assumed to be UTC.

⚠ Deprecated in v4.35.0

Not providing a min_timestamp is deprecated.

max_timestamp : datetime | None Default: None

The maximum timestamp to use when querying data. If the provided datetime doesn’t have a timezone set, it is assumed to be UTC.

limit : int | None Default: None

The maximum number of rows to query. This value takes priority over the LIMIT clause in the sql query.

timezone : str | None Default: None

The timezone to use for the query execution context.

environment : str | list[str] | None Default: None

Restrict rows to the provided environment(s). To only query rows where no environment is set, use the empty string ('').

ReadTokenInfo

Bases: TypedDict

Information about the read token.

RowQueryResults

Bases: TypedDict

The row-oriented results of a JSON-format query.

Attributes

columns

The list of column details (e.g. [{"name": "service_name", "datatype": "Utf8", "nullable": false}]).

Type: list[ColumnDetails]

rows

The list of rows matching the query (e.g. [{"service_name": "backend"}]).

Type: list[dict[str, Any]]

ColumnDetails

Bases: TypedDict

The details of a column in the row-oriented JSON-format query results.

Attributes

name

The name of the column.

Type: str

datatype

The datatype of the column.

Type: Any

nullable

Whether the column is nullable or not.

Type: bool