| Name | dbt-sl-sdk JSON |
| Version |
0.7.0
JSON |
| download |
| home_page | None |
| Summary | A client for dbt's Semantic Layer |
| upload_time | 2024-11-14 18:05:28 |
| maintainer | None |
| docs_url | None |
| author | dbt Labs |
| requires_python | <3.13,>=3.9 |
| license | None |
| keywords |
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# dbt Semantic Layer SDK for Python
A library for easily accessing [dbt's Semantic Layer](https://docs.getdbt.com/docs/use-dbt-semantic-layer/dbt-sl/) via Python.
## Installation
To install the SDK, you'll need to specify optional dependencies depending on whether you want to use it synchronously (backed by [requests](https://github.com/psf/requests/)) or via [asyncio](https://docs.python.org/3/library/asyncio.html) (backed by [aiohttp](https://github.com/aio-libs/aiohttp/)).
```
# Sync installation
pip install "dbt-sl-sdk[sync]"
# Async installation
pip install "dbt-sl-sdk[async]"
```
## Usage
To run operations against the Semantic Layer APIs, just instantiate a `SemanticLayerClient` with your specific connection parameters ([learn more](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-api-overview)):
```python
from dbtsl import SemanticLayerClient
client = SemanticLayerClient(
environment_id=123,
auth_token="<your-semantic-layer-api-token>",
host="semantic-layer.cloud.getdbt.com",
)
# query the first metric by `metric_time`
def main():
with client.session():
metrics = client.metrics()
table = client.query(
metrics=[metrics[0].name],
group_by=["metric_time"],
)
print(table)
main()
```
Note that all method calls that will reach out to the APIs need to be within a `client.session()` context manager. By using a session, the client can connect to the APIs only once, and reuse the same connection between API calls.
### asyncio
If you're using asyncio, import `AsyncSemanticLayerClient` from `dbtsl.asyncio`. The APIs of `SemanticLayerClient` and `AsyncSemanticLayerClient` are the same. The only difference is that the asyncio version has `async` methods which need to be `await`ed.
That same sync example can be converted into asyncio code like so:
```python
import asyncio
from dbtsl.asyncio import AsyncSemanticLayerClient
client = AsyncSemanticLayerClient(
environment_id=123,
auth_token="<your-semantic-layer-api-token>",
host="semantic-layer.cloud.getdbt.com",
)
async def main():
async with client.session():
metrics = await client.metrics()
table = await client.query(
metrics=[metrics[0].name],
group_by=["metric_time"],
)
print(table)
asyncio.run(main())
```
### Integrating with dataframe libraries
By design, the SDK returns all query data as [pyarrow](https://arrow.apache.org/docs/python/index.html) tables. If you wish to use the data with libraries like [pandas](https://pandas.pydata.org/) or [polars](https://pola.rs/), you need to manually download them and convert the data into their format.
If you're using pandas:
```python
# ... initialize client
arrow_table = client.query(...)
pandas_df = arrow_table.to_pandas()
```
If you're using polars:
```python
import polars as pl
# ... initialize client
arrow_table = client.query(...)
polars_df = pl.from_arrow(arrow_table)
```
### More examples
Check out our [usage examples](./examples/) to learn more.
### Disabling telemetry
By default, dbt the SDK sends some [platform-related information](./dbtsl/env.py) to dbt Labs. If you'd like to opt out, do
```python
from dbtsl.env import PLATFORM
PLATFORM.anonymous = True
# ... initialize client
```
## Contributing
If you're interested in contributing to this project, check out our [contribution guidelines](./CONTRIBUTING.md).
Raw data
{
"_id": null,
"home_page": null,
"name": "dbt-sl-sdk",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.13,>=3.9",
"maintainer_email": null,
"keywords": null,
"author": "dbt Labs",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/1c/78/2a3d76da616d7eff2cec07df0d9e5ac3d1f071aa8153211a9c1673488a66/dbt_sl_sdk-0.7.0.tar.gz",
"platform": null,
"description": "# dbt Semantic Layer SDK for Python\n\nA library for easily accessing [dbt's Semantic Layer](https://docs.getdbt.com/docs/use-dbt-semantic-layer/dbt-sl/) via Python.\n\n## Installation\n\nTo install the SDK, you'll need to specify optional dependencies depending on whether you want to use it synchronously (backed by [requests](https://github.com/psf/requests/)) or via [asyncio](https://docs.python.org/3/library/asyncio.html) (backed by [aiohttp](https://github.com/aio-libs/aiohttp/)).\n\n```\n# Sync installation\npip install \"dbt-sl-sdk[sync]\"\n\n# Async installation\npip install \"dbt-sl-sdk[async]\"\n```\n\n## Usage\n\nTo run operations against the Semantic Layer APIs, just instantiate a `SemanticLayerClient` with your specific connection parameters ([learn more](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-api-overview)):\n\n```python\nfrom dbtsl import SemanticLayerClient\n\nclient = SemanticLayerClient(\n environment_id=123,\n auth_token=\"<your-semantic-layer-api-token>\",\n host=\"semantic-layer.cloud.getdbt.com\",\n)\n\n# query the first metric by `metric_time`\ndef main():\n with client.session():\n metrics = client.metrics()\n table = client.query(\n metrics=[metrics[0].name],\n group_by=[\"metric_time\"],\n )\n print(table)\n\nmain()\n```\n\nNote that all method calls that will reach out to the APIs need to be within a `client.session()` context manager. By using a session, the client can connect to the APIs only once, and reuse the same connection between API calls.\n\n### asyncio\n\nIf you're using asyncio, import `AsyncSemanticLayerClient` from `dbtsl.asyncio`. The APIs of `SemanticLayerClient` and `AsyncSemanticLayerClient` are the same. The only difference is that the asyncio version has `async` methods which need to be `await`ed.\n\nThat same sync example can be converted into asyncio code like so:\n\n```python\nimport asyncio\nfrom dbtsl.asyncio import AsyncSemanticLayerClient\n\nclient = AsyncSemanticLayerClient(\n environment_id=123,\n auth_token=\"<your-semantic-layer-api-token>\",\n host=\"semantic-layer.cloud.getdbt.com\",\n)\n\nasync def main():\n async with client.session():\n metrics = await client.metrics()\n table = await client.query(\n metrics=[metrics[0].name],\n group_by=[\"metric_time\"],\n )\n print(table)\n\nasyncio.run(main())\n```\n\n### Integrating with dataframe libraries\n\nBy design, the SDK returns all query data as [pyarrow](https://arrow.apache.org/docs/python/index.html) tables. If you wish to use the data with libraries like [pandas](https://pandas.pydata.org/) or [polars](https://pola.rs/), you need to manually download them and convert the data into their format.\n\nIf you're using pandas:\n```python\n# ... initialize client\n\narrow_table = client.query(...)\npandas_df = arrow_table.to_pandas()\n```\n\nIf you're using polars:\n```python\nimport polars as pl\n\n# ... initialize client\n\narrow_table = client.query(...)\npolars_df = pl.from_arrow(arrow_table)\n```\n\n### More examples\n\nCheck out our [usage examples](./examples/) to learn more.\n\n\n### Disabling telemetry\n\nBy default, dbt the SDK sends some [platform-related information](./dbtsl/env.py) to dbt Labs. If you'd like to opt out, do\n```python\nfrom dbtsl.env import PLATFORM\nPLATFORM.anonymous = True\n\n# ... initialize client\n```\n\n\n## Contributing\n\nIf you're interested in contributing to this project, check out our [contribution guidelines](./CONTRIBUTING.md).\n",
"bugtrack_url": null,
"license": null,
"summary": "A client for dbt's Semantic Layer",
"version": "0.7.0",
"project_urls": null,
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "cbc24990948f5a9c31e42377876b6da28f939f226f1da1d2a607c6b951b79104",
"md5": "ba205270359bb152ce3a8176b40cedc5",
"sha256": "3410933f8d737519f212e6e03af3eae4ea9fe419db177145ddc119be43c3dd0f"
},
"downloads": -1,
"filename": "dbt_sl_sdk-0.7.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ba205270359bb152ce3a8176b40cedc5",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.13,>=3.9",
"size": 39863,
"upload_time": "2024-11-14T18:05:27",
"upload_time_iso_8601": "2024-11-14T18:05:27.114306Z",
"url": "https://files.pythonhosted.org/packages/cb/c2/4990948f5a9c31e42377876b6da28f939f226f1da1d2a607c6b951b79104/dbt_sl_sdk-0.7.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "1c782a3d76da616d7eff2cec07df0d9e5ac3d1f071aa8153211a9c1673488a66",
"md5": "299e0039fc705f7c4b842e083465366f",
"sha256": "7c17d23b4768a7e9d3248afb5e299498b87dd27cd06b967efd3a1158f3afbc64"
},
"downloads": -1,
"filename": "dbt_sl_sdk-0.7.0.tar.gz",
"has_sig": false,
"md5_digest": "299e0039fc705f7c4b842e083465366f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.13,>=3.9",
"size": 23858,
"upload_time": "2024-11-14T18:05:28",
"upload_time_iso_8601": "2024-11-14T18:05:28.885150Z",
"url": "https://files.pythonhosted.org/packages/1c/78/2a3d76da616d7eff2cec07df0d9e5ac3d1f071aa8153211a9c1673488a66/dbt_sl_sdk-0.7.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-14 18:05:28",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "dbt-sl-sdk"
}
