Metadata-Version: 2.1
Name: snuba-sdk
Version: 3.0.42
Summary: Snuba SDK for generating SnQL queries.
Home-page: https://github.com/getsentry/snuba-sdk
Author: Sentry
Author-email: oss@sentry.io
License: FSL-1.0-Apache-2.0
Project-URL: Changelog, https://github.com/getsentry/snuba-sdk/blob/main/CHANGES.rst
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Description-Content-Type: text/x-rst
License-File: LICENSE.md
Requires-Dist: parsimonious>=0.10.0

.. image:: https://sentry-brand.storage.googleapis.com/sentry-wordmark-dark-280x84.png
    :width: 280
    :target: https://sentry.io/?utm_source=github&utm_medium=logo

See here for the full `documentation <https://getsentry.github.io/snuba-sdk/>`_.

======
Status
======

.. image:: https://img.shields.io/pypi/v/snuba-sdk.svg
    :target: https://pypi.python.org/pypi/snuba-sdk

.. image:: https://github.com/getsentry/snuba-sdk/workflows/tests/badge.svg
    :target: https://github.com/getsentry/snuba-sdk/actions

.. image:: https://img.shields.io/discord/621778831602221064
    :target: https://discord.gg/cWnMQeA

=========
Examples
=========

Snuba SDK is a tool that allows requests to Snuba to be built programatically. A Request consists of a Query, the dataset the Query is targeting, the AppID of the Request, and any flags for the Request. A Query object is a code representation of a SnQL or MQL query, and has a number of attributes corresponding to different parts of the query.

Requests and Queries can be created directly:

.. code-block:: python

    request = Request(
        dataset = "discover",
        app_id = "myappid",
        tenant_ids = {"referrer": "my_referrer", "organization_id": 1234}
        query = Query(
            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),
        ),
        flags = Flags(debug=True)
    )


Queries can also be built incrementally:

.. code-block:: python

    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 request is built, it can be translated into a Snuba request that can be sent to Snuba.

.. code-block:: python

    # Outputs a formatted Snuba request
    request.serialize()

It can also be printed in a more human readable format.

.. code-block:: python

    # Outputs a formatted Snuba request
    print(request.print())

This outputs:

.. code-block:: JSON

    {
        "dataset": "discover",
        "app_id": "myappid",
        "query": "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",
        "debug": true
    }

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.
If there is a problem with the Request or the Flags, an ``InvalidRequestError`` or ``InvalidFlagError`` will be thrown respectively.

============
MQL Examples
============

MQL queries can be built in a similar way to SnQL queries. However they use a ``MetricsQuery`` object instead of a ``Query`` object. The ``query`` argument of a ``MetricsQuery`` is either a ``Timeseries`` or ``Formula``, which is a mathemtical formula of ``Timeseries``.

The other arguments to the ``MetricsQuery`` are meta data about how to run the query, e.g. start/end timestamps, the granularity, limits etc.

.. code-block:: python

    MetricsQuery(
        query=Formula(
            ArithmeticOperator.DIVIDE.value,
            [
                Timeseries(
                    metric=Metric(
                        public_name="transaction.duration",
                    ),
                    aggregate="sum",
                ),
                1000,
            ],
        ),
        start=NOW,
        end=NOW + timedelta(days=14),
        rollup=Rollup(interval=3600, totals=None, granularity=3600),
        scope=MetricsScope(
            org_ids=[1], project_ids=[11], use_case_id="transactions"
        ),
        limit=Limit(100),
        offset=Offset(5),
    )


===========================
Contributing to the SDK
===========================

Please refer to `CONTRIBUTING.rst <https://github.com/getsentry/snuba-sdk/blob/master/CONTRIBUTING.rst>`_.

=========
License
=========

Licensed under FSL-1.0-Apache-2.0, see `LICENSE.md <https://github.com/getsentry/snuba-sdk/blob/master/LICENSE.md>`_.
