post

Overview

This endpoint is used for initiating ReadSessions for tables, uploads, and query results. A ReadSession can consist of one or more read streams, which are subsequently consumed via the getStream endpoint.

ReadSessions expire after 6 hours.

When creating a read session for an unreleased table, note that a stream will be returned for each upload on the table, as well as (potentially) for the previous version of the table.

It is possible for these streams to have different schema, and it is the responsibility of the stream consumer(s) to handle accordingly.

HTTP Request

POST /tables/:tableReference/readSessions
POST /uploads/:uploadReference/readSessions
POST /queries/:queryId/readSessions

This endpoint extends the general API structure

Request body

Provide a JSON object with information about the dataset.

Property name	Type	Description
format	string	Optional, default "arrow". The format of the stream results. Must be one of "arrow", "jsonl", or "csv". If arrow, each stream will be encoded the Arrow IPC Stream binary specification. If jsonl, each stream will be encoded as newline-delimited JSON, with each JSON record representing a single row. If csv, each stream will be encoded as a CSV, including a header.
maxResults	string	Optional. Maximum number of rows to return.
selectedVariables	string[]	Optional. A comma separated list of the variables to return, case insensitive. The order of variables in this list will determine the order of values in the response. If not specified, all variables belonging to the table will be returned.
requestedStreamCount	integer	Optional, default 1. The requested number of streams to return. More streams may allow for higher throughput via parallelization. There is no guarantee that the number of streams returned will be equivalent to the requestedStreamCount. If a table is unreleased, at minimum a stream will be returned for each upload on the unreleased table. For other tables, uploads, and query results, the requested stream count will be treated as a maximum, but in certain cases fewer streams may be returned than requested, particularly for smaller tables.
allowAnonymousAccess	bool	Optional, default false. Whether to allow anonymous download to any client with the stream id. Useful for when an API consumer may want to return a stream to another client without that client possessing Redivis API credentials. Extreme care must be taken when using this approach, to ensure that stream ids are not inadvertently leaked to inappropriate actors.

Authorization

Data access to all tables referenced by the query is required. If a table's data is not public, your access token must have one of the following scopes:

• data.data

• data.edit

Learn more about authorization.

Response body

{
  "kind": "readSession",
  "streams": [
    {
      "kind": "readStream",
      "id": str,
      "format": str,     // One of "arrow", "csv", "jsonl"
      "expiresAt": int   // Expiration timestamp, in millisconds since the epoch
    }
  ]
}