Skip to main content
Version: Next

Entry API to Read Data

The API provides several endpoints for reading data from an entry including reading a single record, reading multiple records in a batch, and querying records for a time interval.

Get a Record from an Entry​

The method finds a record for the given timestamp or query ID and sends its content in the HTTP response body. It also sends meta information in headers:

  • x-reduct-time - UNIX timestamp of the record in microseconds
  • x-reduct-label-<name> - a value of the <name> label

If authentication is enabled, the method needs a valid API token with read access to the entry's bucket.

Changes:

  • Version 1.3: the database supports labels. If a record has some labels, the method sends them as headers that start with x-reduct-label.
  • Version 1.4: the x-reduct-last header is deprecated. Use the NoContent response instead.
  • Version 1.16: the x-reduct-last header is removed.
  • Version 1.18: returns 409 Conflict if the bucket or entry is being deleted.
GET
/api/v1/b/:bucket_name/:entry_name
Get a record from an entry

Get a Batch of Records from an Entry​

The method retrieves a batch of records for the given query ID and sends their contents in the HTTP response body.

The method works in conjunction with the GET /b/:bucket/:entry/q method and uses the Batch Protocol to read records in a batch.

If authentication is enabled, the method needs a valid API token with read access to the entry's bucket.

Changes:

  • Version 1.5: the method was introduced.
  • Version 1.18: returns 409 Conflict if the bucket or entry is being deleted.
GET
/api/v1/b/:bucket_name/:entry_name/batch
Get a bulk of records from an entry

Query Records for a Time Interval​

The method responds with a JSON document containing an ID which should be used to read records with the following endpoint: GET /b/:bucket_name/:entry_name?q=ID.

The time interval is [start, stop).

If authentication is enabled, the method needs a valid API token with read access to the bucket of the entry.

Changes:

  • Version 1.3: the method also provides the include-<label> and exclude-<label> query parameters to filter records based on the values of certain labels. For example: 
      GET /api/v1/:bucket/:entry/q?include-<label1>=foo&exclude-<label2>=bar
    This would find all records that have label1 equal to "foo" and excludes those that have label2 equal to "bar". A user can specify multiple include and exclude labels, which will be connected with an AND operator. For example: 
    GET /api/v1/:bucket/:entry/q?include-<label1>=foo&include-<label2>=bar
  • Version 1.4: the method has the continuous flag. If it is true, the current query will not be discarded if there are no records. A client can ask them later. The query will not be removed until its TTL has expired. The stop parameter is ignored for continuous queries.
  • Version 1.6: the method provides the limit query parameter. It limits the number of records in the query. If it is not set, the query is unlimited by default.
  • Version 1.10: the method has the each_n and each_s query parameters. If the each_n parameter is set, the method returns only every each_n-th record. If the each_s parameter is set, the method returns only one record per each_s seconds.
  • Version 1.18: returns 409 Conflict if the bucket or entry is being deleted.
warning

Since version 1.13, the method is deprecated. Use the Query API instead.

GET
/api/v1/b/:bucket_name/:entry_name/q
Query records for a time interval

Reading only meta information​

Sometimes you need to retrieve only the meta information about a record without its content, ReductStore provides the HEAD version of the read endpoints for this purpose.

HEAD
/api/v1/b/:bucket_name/:entry_name
Get only meta information about record
HEAD
/api/v1/b/:bucket_name/:entry_name/batch
Get only meta information in bulk