Skip to main content

Official Sage data client.

Project description

Sage Data Client

This is the official Sage Python data API client. Its main goal is to make writing queries and working with the results easy. It does this by:

  1. Providing a simple query function which talks to the data API.
  2. Providing the results in an easy to use Pandas data frame.

Installation

Sage Data Client can be installed with pip using:

pip3 install sage-data-client

If you prefer to install this package into a Python virtual environment or are unable to install it system wide, you can use the venv module as follows:

# 1. Create a new virtual environment called my-venv.
python3 -m venv my-venv

# 2. Activate the virtual environment
source my-venv/bin/activate

# 3. Install sage data client in the virtual environment
pip3 install sage-data-client

Note: If you are using Linux, you may need to install the python3-venv package which is outside of the scope of this document.

Note: You will need to activate this virtual environment when opening a new terminal before running any Python scripts using Sage Data Client.

Usage Examples

Query API

import sage_data_client

# query and load data into pandas data frame
df = sage_data_client.query(
    start="-1h",
    filter={
        "name": "env.temperature",
    }
)

# print results in data frame
print(df)

# meta columns are expanded into meta.fieldname. for example, here we print the unique nodes
print(df["meta.vsn"].unique())

# print stats of the temperature data grouped by node + sensor.
print(df.groupby(["meta.vsn", "meta.sensor"]).value.agg(["size", "min", "max", "mean"]))
import sage_data_client

# query and load data into pandas data frame
df = sage_data_client.query(
    start="-1h",
    filter={
        "name": "env.raingauge.*",
    }
)

# print number of results of each name
print(df.groupby(["meta.vsn", "name"]).size())

Load results from file

If we have saved the results of a query to a file data.json, we can also load using the load function as follows:

import sage_data_client

# load results from local file
df = sage_data_client.load("data.json")

# print number of results of each name
print(df.groupby(["meta.vsn", "name"]).size())

Integration with Notebooks

Since we leverage the fantastic work provided by the Pandas library, performing things like looking at dataframes or creating plots is easy.

A basic example of querying and plotting data can be found here.

Additional Examples

Additional code examples can be found in the examples directory.

If you're interested in contributing your own examples, feel free to add them to examples/contrib and open a PR!

Reference

The query function accepts the following arguments:

  • start. Absolute or relative start timestamp. (required)
  • end. Absolute or relative end timestamp.
  • head. Limit results to head earliest values per series. (Only one of head or tail can be provided.)
  • tail. Limit results to tail latest values per series. (Only one of head or tail can be provided.)
  • filter. Key-value patterns to filter data on.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

sage_data_client-0.9.0.tar.gz (7.3 kB view details)

Uploaded Source

Built Distribution

sage_data_client-0.9.0-py3-none-any.whl (6.4 kB view details)

Uploaded Python 3

File details

Details for the file sage_data_client-0.9.0.tar.gz.

File metadata

  • Download URL: sage_data_client-0.9.0.tar.gz
  • Upload date:
  • Size: 7.3 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.0.1 CPython/3.10.12

File hashes

Hashes for sage_data_client-0.9.0.tar.gz
Algorithm Hash digest
SHA256 f1f343e97a3158df3d57a5fd3fb8bbda43dbea8ebe3a00e103e19a1dc2b22281
MD5 a1b42bf4f7c2bde5711a65aebca0b402
BLAKE2b-256 49a86fe8ba46c4799f71a7fe68e03b5ed705a8c95413c28b3168eea5857c5983

See more details on using hashes here.

File details

Details for the file sage_data_client-0.9.0-py3-none-any.whl.

File metadata

File hashes

Hashes for sage_data_client-0.9.0-py3-none-any.whl
Algorithm Hash digest
SHA256 2bd5f432fb2e5f88395704e0596d7d6cae8cd4cad3a5f439355dc3b5a5fb9e03
MD5 f46012d063b8fd0d247ea66c237c3505
BLAKE2b-256 5051c2387bf54e94a3c32701a75ddc71e11d6eadd4a35ae6791caf35d65b7ca4

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page