Axibase Time Series Database

Properties: query

Description

Retrieves property records for the specified filters including type, entity, key, and time range.

Basic example:

[{
  "type": "disk",
  "entity": "nurswgvml007",
  "startDate": "now - 1 * DAY",
  "endDate": "now",
}]

Request

Method Path Content-Type Header
POST /api/v1/properties/query application/json

Parameters

None.

Fields

An array of query objects containing the following filtering fields:

Property Filter Fields

Name Type Description
type string [Required] Property type name.
Use $entity_tags type to retrieve entity tags.
key object Object with name=value fields, for example "key": {"file_system": "/"}
Matches records with exact or partial key fields based on the exactMatch parameter value.
exactMatch boolean key match operator. Exact match if true, partial match if false.
Default: false.
Exact match selects a record with exactly the same key as requested.
Partial match selects records with key that contains requested fields but can also include other fields.
keyTagExpression string Expression for matching properties with specified keys or tags.
Example: keys.file_system LIKE '/u*' or tags.fs_type == 'ext4'.
Use lower() function to ignore case, for example lower(keys.file_system) LIKE '/u*'
  • Key values and tag values are case-sensitive.
  • Key names and tag names are case-insensitive.

Entity Filter Fields

Date Filter Fields

Record Filter

The filter applies if exactMatch is false and multiple records matched the query. The filter compares the timestamp of the record with the maximum timestamp of all matched records.

Name Type Description
last boolean Includes records with the timestamp equal the maximum timestamp of matched records.
Default: false.
offset integer Includes records based on difference, in milliseconds, between maximum timestamp of matched records and timestamp of the current record.
The record is included in results if its timestamp is greater than or equal maximum timestamp less the offset.
Offset of 0 is equivalent to last=true.
Default: -1 (not applied).

Field Filter

Name Type Description
merge boolean Returns all tag values within the record.
If set to false, only tag values with update time equal to the row timestamp are included.
Default: false.

Control Fields

Name Type Description
limit integer Maximum number of rows returned.
Default: 0 (no limit).
The parameter is ignored if the value is negative or 0.
addMeta boolean Include metric and entity metadata fields under the meta object in response.
Default: false.

Response

An array of matching property objects containing the following fields:

Fields

Name Type Description
type string Property type name.
entity string Entity name.
key object Object containing name=value fields that uniquely identify the property record.
Example: {"file_system": "/","mount_point":"sda1"}
tags object Object containing name=value fields that are not part of the key and contain descriptive information about the property record.
Example: {"fs_type": "ext4"}.
date string Date of last modified property record in ISO format.

Key Match Example

Assuming property records A,B,C, and D exist:

| record | type   | entity | key-1 | key-2 |
|--------|--------|--------|-------|-------|
| A      | type-1 | e-1    | val-1 | val-2 |
| B      | type-1 | e-2    | val-1 |       |
| C      | type-1 | e-3    |       | VAL-3 |
| D      | type-1 | e-4    |       |       |

The table below illustrates which records are returned (the result column) for the corresponding exactMatch and key parameters on the left.

| exactMatch | key                     | result  |
|------------|-------------------------|---------|
| true       |                         | D       |
| false      |                         | A;B;C;D |
| true       | key-1=val-1             | B       |
| false      | key-1=val-1             | A;B     |
| true       | key-1=val-1;key-2=val-2 | A       |
| false      | key-1=val-1;key-2=val-2 | A       |
| false      | key-2=val-3             |         |
| false      | key-2=VAL-3             | C       |

Offset Example

Assuming property records A,B,C, and D exist and time represents their update time in milliseconds:

| record | type   | entity | key-1 | time |
|--------|--------|--------|-------|------|
| A      | type-1 | e-1    | val-1 |  100 |
| B      | type-1 | e-2    | val-2 |  200 |
| C      | type-1 | e-3    | val-1 |  200 |
| D      | type-1 | e-4    | val-2 |  150 |

max(time) = 200

The table below illustrates which records are returned (the result column) for the offset parameter on the left.

| offset | result  |
|     -1 | A;B;C;D | Offset filter is not applied.
|      0 | B;C     | Only records with update time = max(time) are included.
|      1 | B;C     |
|     50 | B;C;D   | D time difference = max(time)-150=50. D is included because difference is <= offset of 50.
|    200 | A;B;C;D | Time difference for all records is <= offset of 200. All records included.

Example

Request

URI

POST /api/v1/properties/query

Payload

[{
  "type": "disk",
  "entity": "nurswgvml007",
  "key": { "file_system": "/" },
  "startDate": "2016-05-25T04:00:00Z",
  "endDate":   "2016-05-25T05:00:00Z"
}]

curl

curl https://atsd_hostname:8443/api/v1/properties/query \
  -k --user {username}:{password} \
  --header "Content-Type: application/json" \
  --data '[{"type":"disk","entity":"nurswgvml007","key":{"file_system":"/"},"startDate":"2016-05-25T04:00:00Z","endDate":"2016-05-25T05:00:00Z"}]'

Response

[
   {
       "type": "disk",
       "entity": "nurswgvml007",
       "key": {
           "file_system": "/",
           "mount_point": "sda1"
       },
       "tags": {
           "fs_type": "ext4"
       },
       "date": "2016-05-25T04:15:00Z"
   }
]

Java Example

Additional Examples

Filters

Control Fields

← get types →