SDK for generating SnQL queries for Snuba

https://sentry-brand.storage.googleapis.com/sentry-logo-black.png

See here for the full documentation.

Status

https://img.shields.io/pypi/v/snuba-sdk.svg https://github.com/getsentry/snuba-sdk/workflows/tests/badge.svg https://img.shields.io/discord/621778831602221064

Examples

Snuba SDK is a tool that allows SnQL queries (the language that Snuba uses) to be built programatically. A SnQL query is represented by a Query object, and has a number of attributes corresponding to different parts of the query.

Queries can be created directly:

query = Query(
    dataset="discover",
    match=Entity("events"),
    select=[
        Column("title"),
        Function("uniq", [Column("event_id")], "uniq_events"),
    ],
    groupby=[Column("title")],
    where=[
        Condition(Column("timestamp"), Op.GT, datetime.datetime(2021, 1, 1)),
        Condition(Column("project_id"), Op.IN, Function("tuple", [1, 2, 3])),
    ],
    limit=Limit(10),
    offset=Offset(0),
    granularity=Granularity(3600),
)

Queries can also be built incrementally:

query = Query("discover", Entity("events"))
.set_select(
    [Column("title"), Function("uniq", [Column("event_id")], "uniq_events")]
)
.set_groupby([Column("title")])
.set_where(
    [
        Condition(Column("timestamp"), Op.GT, datetime.datetime.(2021, 1, 1)),
        Condition(Column("project_id"), Op.IN, Function("tuple", [1, 2, 3])),
    ]
)
.set_limit(10)
.set_offset(0)
.set_granularity(3600)

Once the query is built, it can be translated into a SnQL query that can be sent to Snuba or a human readable query.

# Outputs a formatted SnQL query
print(query.print())

This outputs:

MATCH (events)
SELECT title, uniq(event_id) AS uniq_events
BY title
WHERE timestamp > toDateTime('2021-01-01T00:00:00.000000')
AND project_id IN tuple(1, 2, 3)
LIMIT 10
OFFSET 0
GRANULARITY 3600

If an expression in the query is invalid (e.g. Column(1)) then an InvalidExpressionError exception will be thrown. If there is a problem with a query, it will throw an InvalidQueryError exception when .validate() or .translate() is called.

Contributing to the SDK

Please refer to CONTRIBUTING.rst.

License

Licensed under MIT, see LICENSE.

Indices and tables