.. 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>`_.
Raw data
{
"_id": null,
"home_page": "https://github.com/getsentry/snuba-sdk",
"name": "snuba-sdk",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": null,
"author": "Sentry",
"author_email": "oss@sentry.io",
"download_url": null,
"platform": null,
"description": ".. image:: https://sentry-brand.storage.googleapis.com/sentry-wordmark-dark-280x84.png\n :width: 280\n :target: https://sentry.io/?utm_source=github&utm_medium=logo\n\nSee here for the full `documentation <https://getsentry.github.io/snuba-sdk/>`_.\n\n======\nStatus\n======\n\n.. image:: https://img.shields.io/pypi/v/snuba-sdk.svg\n :target: https://pypi.python.org/pypi/snuba-sdk\n\n.. image:: https://github.com/getsentry/snuba-sdk/workflows/tests/badge.svg\n :target: https://github.com/getsentry/snuba-sdk/actions\n\n.. image:: https://img.shields.io/discord/621778831602221064\n :target: https://discord.gg/cWnMQeA\n\n=========\nExamples\n=========\n\nSnuba 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.\n\nRequests and Queries can be created directly:\n\n.. code-block:: python\n\n request = Request(\n dataset = \"discover\",\n app_id = \"myappid\",\n tenant_ids = {\"referrer\": \"my_referrer\", \"organization_id\": 1234}\n query = Query(\n match=Entity(\"events\"),\n select=[\n Column(\"title\"),\n Function(\"uniq\", [Column(\"event_id\")], \"uniq_events\"),\n ],\n groupby=[Column(\"title\")],\n where=[\n Condition(Column(\"timestamp\"), Op.GT, datetime.datetime(2021, 1, 1)),\n Condition(Column(\"project_id\"), Op.IN, Function(\"tuple\", [1, 2, 3])),\n ],\n limit=Limit(10),\n offset=Offset(0),\n granularity=Granularity(3600),\n ),\n flags = Flags(debug=True)\n )\n\n\nQueries can also be built incrementally:\n\n.. code-block:: python\n\n query = (\n Query(\"discover\", Entity(\"events\"))\n .set_select(\n [Column(\"title\"), Function(\"uniq\", [Column(\"event_id\")], \"uniq_events\")]\n )\n .set_groupby([Column(\"title\")])\n .set_where(\n [\n Condition(Column(\"timestamp\"), Op.GT, datetime.datetime.(2021, 1, 1)),\n Condition(Column(\"project_id\"), Op.IN, Function(\"tuple\", [1, 2, 3])),\n ]\n )\n .set_limit(10)\n .set_offset(0)\n .set_granularity(3600)\n )\n\n\nOnce the request is built, it can be translated into a Snuba request that can be sent to Snuba.\n\n.. code-block:: python\n\n # Outputs a formatted Snuba request\n request.serialize()\n\nIt can also be printed in a more human readable format.\n\n.. code-block:: python\n\n # Outputs a formatted Snuba request\n print(request.print())\n\nThis outputs:\n\n.. code-block:: JSON\n\n {\n \"dataset\": \"discover\",\n \"app_id\": \"myappid\",\n \"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\",\n \"debug\": true\n }\n\nIf an expression in the query is invalid (e.g. ``Column(1)``) then an ``InvalidExpressionError`` exception will be thrown.\nIf there is a problem with a query, it will throw an ``InvalidQueryError`` exception when ``.validate()`` or ``.translate()`` is called.\nIf there is a problem with the Request or the Flags, an ``InvalidRequestError`` or ``InvalidFlagError`` will be thrown respectively.\n\n============\nMQL Examples\n============\n\nMQL 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``.\n\nThe other arguments to the ``MetricsQuery`` are meta data about how to run the query, e.g. start/end timestamps, the granularity, limits etc.\n\n.. code-block:: python\n\n MetricsQuery(\n query=Formula(\n ArithmeticOperator.DIVIDE.value,\n [\n Timeseries(\n metric=Metric(\n public_name=\"transaction.duration\",\n ),\n aggregate=\"sum\",\n ),\n 1000,\n ],\n ),\n start=NOW,\n end=NOW + timedelta(days=14),\n rollup=Rollup(interval=3600, totals=None, granularity=3600),\n scope=MetricsScope(\n org_ids=[1], project_ids=[11], use_case_id=\"transactions\"\n ),\n limit=Limit(100),\n offset=Offset(5),\n )\n\n\n===========================\nContributing to the SDK\n===========================\n\nPlease refer to `CONTRIBUTING.rst <https://github.com/getsentry/snuba-sdk/blob/master/CONTRIBUTING.rst>`_.\n\n=========\nLicense\n=========\n\nLicensed under FSL-1.0-Apache-2.0, see `LICENSE.md <https://github.com/getsentry/snuba-sdk/blob/master/LICENSE.md>`_.\n",
"bugtrack_url": null,
"license": "FSL-1.0-Apache-2.0",
"summary": "Snuba SDK for generating SnQL queries.",
"version": "2.0.34",
"project_urls": {
"Changelog": "https://github.com/getsentry/snuba-sdk/blob/main/CHANGES.rst",
"Homepage": "https://github.com/getsentry/snuba-sdk"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "8f9f204cecaa1ee69f39efa809848af54909b78fe53f1ba4fae0d92bfefa9bf1",
"md5": "67ba18c13b02418ec5bb3df9949edc30",
"sha256": "1a28a771f5cd20b54721665e6ae0bc92b707ac80f174f1f8e39c4446df1a556d"
},
"downloads": -1,
"filename": "snuba_sdk-2.0.34-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "67ba18c13b02418ec5bb3df9949edc30",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 48992,
"upload_time": "2024-05-09T16:17:30",
"upload_time_iso_8601": "2024-05-09T16:17:30.994326Z",
"url": "https://files.pythonhosted.org/packages/8f/9f/204cecaa1ee69f39efa809848af54909b78fe53f1ba4fae0d92bfefa9bf1/snuba_sdk-2.0.34-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-09 16:17:30",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "getsentry",
"github_project": "snuba-sdk",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "snuba-sdk"
}
JSON
