Axibase Time-Series Database Client for Python

The Axibase Time-Series Database API Client for Python enables developers to easily read and write statistics and metadata from Axibase Time-Series Database.

API documentation
PyPI
Client documentation

Installation

Install atsd_client with pip

pip install atsd_client

or clone GitHub repository and run

python setup.py install

Usage

###Connecting to ATSD

To retrieve data from the Axibase Time-Series Database (ATSD), establish a connection with atsd_client module as follows:

>>>importatsd_client>>>fromatsd_clientimportservices, models>>>>>>conn=atsd_client.connect()

###Initializing the Service

The Service implements a set of methods for interacting with a particular type of objects in ATSD, for example, Series, Property, Alert objects as well as with metadata objects such as Entity, Metric, EntityGroup.

>>>svc=services.SeriesService(conn)

###Inserting Series Values

To insert series values into ATSD initialize a Series object and populate it with timestamped values.

>>>series=models.Series('sensor001', 'temperature')
>>>series.add_value(3, '2015-04-14T07:03:31Z')
>>>>>>svc.insert_series(series)

add version information with an optional version argument

>>>series.add_value(3, '2015-04-14T07:03:31Z', version={'source': 'manual'})

###Querying Series Values

When querying series values from ATSD you need to specify metric, entity, as well as start and end time. The retrieve_series method returns a list of Series objects, which you can unpack using series, = svc.retrieve_series function.

>>>importtime>>>>>>query=models.SeriesQuery('sensor001', 'temperature')
>>>now=int(time.time() *1000) # current time in unix milliseconds>>>query.endTime=now>>>query.startTime=now-12*60*60*1000# query data for the last 12 hours>>>>>>series, =svc.retrieve_series(query)
>>>>>>print(series)
2015-11-19T12:05:44Z2.02015-11-19T12:08:19Z2.02015-11-19T12:08:19Z34.02015-11-19T12:08:19Z3.02015-11-19T12:15:44Z4.02015-11-19T14:34:36Z15.02015-11-19T15:20:07Z36.02015-11-19T15:20:33Z11.02015-11-19T15:20:55Z40.02015-11-19T15:21:13Z45.0
...
2015-11-19T16:20:17Z45.02015-11-19T16:46:10Z55.02015-11-19T17:24:34Z62.02015-11-19T17:38:14Z42.02015-11-19T18:38:58Znan2015-11-19T18:43:58Z14.02015-11-20T09:42:02Z24.02015-11-20T10:36:03Z35.02015-11-20T10:49:53Z11.02015-11-20T11:09:06Z33.0metric: temperatureentity: sensor001aggregate: {u'type': u'DETAIL'}
type: HISTORY

Alternatively you can specify startTime and endTime properties using the built-in datetime object

>>>fromdatetimeimportdatetime>>>fromdatetimeimporttimedelta>>>>>>query.endTime=datetime.now()
>>>query.startTime=query.endTime-timedelta(hours=12)

###Querying Versioned Series Values

To fetch series values with version information add query.versioned = True

>>>importtime>>>>>>query=models.SeriesQuery('sensor001', 'temperature')
>>>now=int(time.time() *1000) # current time in unix milliseconds>>>query.versioned=True>>>query.endTime=now>>>query.startTime=now-12*60*60*1000# query data for the last 12 hours>>>>>>series, =svc.retrieve_series(query)
>>>series.sort(key=lambdasample: sample['version']['t'])
>>>print(series)
timestampvalueversion_sourceversion_statusversion_time2015-11-19T12:05:44Z2.0gateway-1OK2015-11-19T12:14:32Z2015-11-19T12:08:19Z2.0gateway-1OK2015-11-19T12:09:59Z2015-11-19T12:08:19Z34.0gateway-1OK2015-11-19T12:10:27Z2015-11-19T12:08:19Z3.0gateway-1OK2015-11-19T12:12:58Z2015-11-19T12:15:44Z4.0gateway-1OK2015-11-19T12:15:56Z2015-11-19T14:34:36Z15.0gateway-1OK2015-11-19T14:35:54Z2015-11-19T15:20:07Z36.0gateway-1OK2015-11-19T15:20:06Z2015-11-19T15:20:33Z11.0gateway-1OK2015-11-19T15:20:32Z2015-11-19T15:20:55Z40.0gateway-1OK2015-11-19T15:20:53Z2015-11-19T15:21:13Z45.0gateway-1OK2015-11-19T15:21:12Z
...
2015-11-19T16:46:10Z55.0gateway-1OK2015-11-19T16:46:11Z2015-11-19T17:24:34Z62.0gateway-1OK2015-11-19T17:24:35Z2015-11-19T17:38:14Z42.0gateway-1OK2015-11-19T17:38:15Z2015-11-19T18:38:58Z1094.0gateway-1OK2015-11-19T18:38:59Z2015-11-19T18:43:58Z14.0gateway-1OK2015-11-19T18:43:59Z2015-11-20T09:42:02Z24.0gateway-1OK2015-11-20T09:42:03Z2015-11-20T10:36:03Z35.0gateway-1OK2015-11-20T10:36:05Z2015-11-20T10:49:53Z11.0gateway-1OK2015-11-20T10:49:54Z2015-11-20T11:09:06Z33.0gateway-1OK2015-11-20T11:09:39Z2015-11-19T18:38:58Znanform/manualOK2015-11-20T18:39:43Zmetric: temperatureentity: sensor001aggregate: {u'type': u'DETAIL'}
type: HISTORY

###Exploring Results

In order to consume the Series object in [pandas, a Python data analysis toolkit] (http://pandas.pydata.org/), you can utilize the built-in to_pandas_series() and from_pandas_series() methods.

>>>ts=series.to_pandas_series()
>>> type(ts.index)
<class'pandas.tseries.index.DatetimeIndex'>>>>print(s)
2015-04-1017:22:24.048000112015-04-1017:23:14.893000312015-04-1017:24:49.05800072015-04-1017:25:15.567000222015-04-1314:00:49.28500092015-04-1315:00:383

###Graphing Results

To plot series with matplotlib use the built-in plot() method

>>>importmatplotlib.pyplotasplt>>>series.plot()
>>>plt.show()

Implemented Methods

Data API

• Series
  • Query
  • Insert
• Properties
  • Query
  • Insert
  • Batch
• Alerts
  • Query
  • Update
  • History Query

Meta API

• Metrics
  • List
  • Get
  • Create or replace
  • Update
  • Delete
  • Entities and tags
• Entities
  • List
  • Get
  • Create or replace
  • Update
  • Delete
• Entity Group
  • List
  • Get
  • Create or replace
  • Update
  • Delete
  • Get entities
  • Add entities
  • Set entities
  • Delete entities