Rockset API Reference

The Rockset API allows you to programmatically access and manage your Rockset resources and features. It follows REST architectural principles, and speaks exclusively in JSON.

The base URL of the Rockset API servers are as follows. You can double check the region of your org by looking at the top-left region dropdown in the Rockset Console.

Region	Base URL
Oregon (us-west-2)	`https://api.rs2.usw2.rockset.com`
N. Virginia (us-east-1)	`https://api.use1a1.rockset.com`

All endpoints are accessible through HTTPS only, ensuring that all data in flight is fully encrypted using TLS.

All requests made to the Rockset API should be formatted using JSON and have the Content-Type header set to application/json in order to ensure that they are read and processed properly.

Authentication

The Rockset API uses API keys to authenticate requests. They can be created and managed in the Rockset Console. The API key must be provided as ApiKey { api_key } in the Authorization request header.

For example, the following request header is properly formatted:

Authorization: ApiKey aB35kDjg931J5nsf4GjwMeErAVd832F7ahsW1S02kfZiab42s11TsfW5Sxt25asT

You can read more about Rockset's authentication & authorization features here.

Queries

QueryResponse Type

Attributes

query_idoptionalstring

Unique ID for this query.

collectionsoptionalarray

List of collections referenced in the query.

resultsoptionalarray

Results from the query.

statsoptional

Meta information about the query including execution latencies.

warningsoptionalarray

Warnings generated by the query. Only populated if generate_warnings is specified in the query request.

query_errorsoptionalarray

Errors encountered while executing the query.

column_fieldsoptionalarray

Meta information about each column in the result set. Not populated in SELECT * queries.

results_total_doc_countoptionalinteger

Number of results generated by the query

paginationoptional

Pagination information. Only populated if paginate is specified in the query request.

last_offsetoptionalstring

If this was a write query, this is the log offset the query was written to

Example Object

{
  "collections": [
    null
  ],
  "results": [
    {}
  ],
  "stats": {
    "elapsed_time_ms": 126,
    "throttled_time_micros": 126
  },
  "warnings": [
    null
  ],
  "column_fields": [
    {
      "name": "_id",
      "type": "string"
    }
  ],
  "pagination": {
    "current_page_doc_count": 1000,
    "next_cursor_offset": 2000,
    "start_cursor": "startcursor",
    "next_cursor": "testnextcursor"
  }
}

Query

Make a SQL query to Rockset.

POST /v1/orgs/self/queries

Arguments

sqlrequiredobject
Main query request body.
Show child attributes

Example Request

Example Response

curl --request POST \
    --url https://api.rs2.usw2.rockset.com/v1/orgs/self/queries \
    -H 'Authorization: ApiKey aB35kDjg93J5nsf4GjwMeErAVd832F7ad4vhsW1S02kfZiab42sTsfW5Sxt25asT' \
  -H 'Content-Type: application/json' \
    -d '{
    "sql": {
      "query": "SELECT * FROM foo where _id = :_id",
      "parameters": [
        {
          "name": "_id",
          "type": "string",
          "value": "85beb391"
        }
      ]
    }
  }'

Validate Query

Validate a SQL query with Rockset's parser and planner.

POST /v1/orgs/self/queries/validations

Arguments

sqlrequiredobject
Main query request body.
Show child attributes

Example Request

Example Response

curl --request POST \
    --url https://api.rs2.usw2.rockset.com/v1/orgs/self/queries/validations \
    -H 'Authorization: ApiKey aB35kDjg93J5nsf4GjwMeErAVd832F7ad4vhsW1S02kfZiab42sTsfW5Sxt25asT' \
  -H 'Content-Type: application/json' \
    -d '{
    "sql": {
      "query": "SELECT * FROM foo where _id = :_id",
      "parameters": [
        {
          "name": "_id",
          "type": "string",
          "value": "85beb391"
        }
      ]
    }
  }'

Documents

Add Documents

Add documents to a collection.

POST /v1/orgs/self/ws/{workspace}/collections/{collection}/docs

Arguments

workspacerequiredstring(in path)
Name of the workspace.
collectionrequiredstring(in path)
Name of the collection.
datarequiredarray
Array of documents to be added to the collection.

Example Request

Example Response

curl --request POST \
    --url https://api.rs2.usw2.rockset.com/v1/orgs/self/ws/commons/collections/customers/docs \
    -H 'Authorization: ApiKey aB35kDjg93J5nsf4GjwMeErAVd832F7ad4vhsW1S02kfZiab42sTsfW5Sxt25asT' \
  -H 'Content-Type: application/json' \
    -d '{
    "data": [
      {
        "field": "value"
      }
    ]
  }'

Delete Documents

Delete documents from a collection.

DELETE /v1/orgs/self/ws/{workspace}/collections/{collection}/docs

Arguments

workspacerequiredstring(in path)
Name of the workspace.
collectionrequiredstring(in path)
Name of the collection.
datarequiredarray
Array of IDs of documents to be deleted
Show child attributes

Example Request

Example Response

curl --request DELETE \
    --url https://api.rs2.usw2.rockset.com/v1/orgs/self/ws/commons/collections/customers/docs \
    -H 'Authorization: ApiKey aB35kDjg93J5nsf4GjwMeErAVd832F7ad4vhsW1S02kfZiab42sTsfW5Sxt25asT' \
  -H 'Content-Type: application/json' \
    -d '{
    "data": [
      {
        "_id": "2cd61e3b"
      }
    ]
  }'

Patch Documents

Update existing documents in a collection.

PATCH /v1/orgs/self/ws/{workspace}/collections/{collection}/docs

Arguments

workspacerequiredstring(in path)
Name of the workspace.
collectionrequiredstring(in path)
Name of the collection.
datarequiredarray
List of patches to be applied.
Show child attributes

Example Request

Example Response

curl --request PATCH \
    --url https://api.rs2.usw2.rockset.com/v1/orgs/self/ws/commons/collections/customers/docs \
    -H 'Authorization: ApiKey aB35kDjg93J5nsf4GjwMeErAVd832F7ad4vhsW1S02kfZiab42sTsfW5Sxt25asT' \
  -H 'Content-Type: application/json' \
    -d '{
    "data": [
      {
        "_id": "ca2d6832-1bfd-f88f-0620-d2aa27a5d86c",
        "patch": [
          {
            "op": "ADD",
            "path": "/foo/bar",
            "value": {
              "type": "object",
              "example": "baz",
              "description": "Value used in the patch operation. Required for `ADD`, `REPLACE`, `TEST`, and `INCREMENT` operations."
            }
          }
        ]
      }
    ]
  }'

API Keys

Create API Key

Create a new API key for the authenticated user.

POST /v1/orgs/self/users/self/apikeys

Arguments

namerequiredstring
Name for this API key.
roleoptionalstring

Example Request

Example Response

curl --request POST \
    --url https://api.rs2.usw2.rockset.com/v1/orgs/self/users/self/apikeys \
    -H 'Authorization: ApiKey aB35kDjg93J5nsf4GjwMeErAVd832F7ad4vhsW1S02kfZiab42sTsfW5Sxt25asT' \
  -H 'Content-Type: application/json' \
    -d '{
    "name": "my-app"
  }'

Delete API Key

Delete an API key for any user in your organization.

DELETE /v1/orgs/self/users/{user}/apikeys/{name}

Arguments

namerequiredstring(in path)
Name of the API key.
userrequiredstring(in path)
Email of the API key owner. Use self to specify the currently authenticated user.

Example Request

Example Response

curl --request DELETE \
    --url https://api.rs2.usw2.rockset.com/v1/orgs/self/users/admin@me.com/apikeys/name \
    -H 'Authorization: ApiKey aB35kDjg93J5nsf4GjwMeErAVd832F7ad4vhsW1S02kfZiab42sTsfW5Sxt25asT'

List API Keys.

List API key metadata for any user in your organization.

GET /v1/orgs/self/users/{user}/apikeys

Arguments

userrequiredstring(in path)
Email of the API key owner. Use self to specify the currently authenticated user.

Example Request

Example Response

curl --request GET \
    --url https://api.rs2.usw2.rockset.com/v1/orgs/self/users/admin@me.com/apikeys \
    -H 'Authorization: ApiKey aB35kDjg93J5nsf4GjwMeErAVd832F7ad4vhsW1S02kfZiab42sTsfW5Sxt25asT'

Retrieve API Key

Retrieve a particular API key for any user in your organization.

GET /v1/orgs/self/users/{user}/apikeys/{name}

Arguments

userrequiredstring(in path)
Email of the API key owner. Use self to specify the currently authenticated user.
namerequiredstring(in path)
Name of the API key.

Example Request

Example Response

curl --request GET \
    --url https://api.rs2.usw2.rockset.com/v1/orgs/self/users/admin@me.com/apikeys/name \
    -H 'Authorization: ApiKey aB35kDjg93J5nsf4GjwMeErAVd832F7ad4vhsW1S02kfZiab42sTsfW5Sxt25asT'

Update an API key's state

Update the state of an API key for any user in your organization.

POST /v1/orgs/self/users/{user}/apikeys/{name}

Arguments

namerequiredstring(in path)
Name of the API key.
userrequiredstring(in path)
Email of the API key owner. Use self to specify the currently authenticated user.
stateoptionalstring
State that the api key should be set to.

Example Request

Example Response

curl --request POST \
    --url https://api.rs2.usw2.rockset.com/v1/orgs/self/users/admin@me.com/apikeys/name \
    -H 'Authorization: ApiKey aB35kDjg93J5nsf4GjwMeErAVd832F7ad4vhsW1S02kfZiab42sTsfW5Sxt25asT' \
  -H 'Content-Type: application/json' \
    -d '{
    "state": "ACTIVE"
  }'

Aliases

Create Alias

Create new alias in a workspace.

POST /v1/orgs/self/ws/{workspace}/aliases

Arguments

workspacerequiredstring(in path)
name of the workspace
namerequiredstring
Alias name
descriptionoptionalstring
optional description
collectionsrequiredarray
list of fully qualified collection names referenced by alias

Example Request

Example Response

curl --request POST \
    --url https://api.rs2.usw2.rockset.com/v1/orgs/self/ws/commons/aliases \
    -H 'Authorization: ApiKey aB35kDjg93J5nsf4GjwMeErAVd832F7ad4vhsW1S02kfZiab42sTsfW5Sxt25asT' \
  -H 'Content-Type: application/json' \
    -d '{
    "name": "aliasName",
    "description": "version alias",
    "collections": [
      "commons.foo",
      "prod.demo"
    ]
  }'

Delete Alias

Delete an alias.

DELETE /v1/orgs/self/ws/{workspace}/aliases/{alias}

Arguments

workspacerequiredstring(in path)
name of the workspace
aliasrequiredstring(in path)
name of the alias

Example Request

Example Response

curl --request DELETE \
    --url https://api.rs2.usw2.rockset.com/v1/orgs/self/ws/commons/aliases/alias \
    -H 'Authorization: ApiKey aB35kDjg93J5nsf4GjwMeErAVd832F7ad4vhsW1S02kfZiab42sTsfW5Sxt25asT'

List Aliases

Retrieve all aliases in an organization

GET /v1/orgs/self/aliases

Arguments

No arguments.

Example Request

Example Response

curl --request GET \
    --url https://api.rs2.usw2.rockset.com/v1/orgs/self/aliases \
    -H 'Authorization: ApiKey aB35kDjg93J5nsf4GjwMeErAVd832F7ad4vhsW1S02kfZiab42sTsfW5Sxt25asT'

List Aliases in Workspace

Retrieve all aliases in a workspace.

GET /v1/orgs/self/ws/{workspace}/aliases

Arguments

workspacerequiredstring(in path)
name of the workspace

Example Request

Example Response

curl --request GET \
    --url https://api.rs2.usw2.rockset.com/v1/orgs/self/ws/commons/aliases \
    -H 'Authorization: ApiKey aB35kDjg93J5nsf4GjwMeErAVd832F7ad4vhsW1S02kfZiab42sTsfW5Sxt25asT'

Retrieve Alias

Get details about an alias

GET /v1/orgs/self/ws/{workspace}/aliases/{alias}

Arguments

workspacerequiredstring(in path)
name of the workspace
aliasrequiredstring(in path)
name of the alias

Example Request

Example Response

curl --request GET \
    --url https://api.rs2.usw2.rockset.com/v1/orgs/self/ws/commons/aliases/alias \
    -H 'Authorization: ApiKey aB35kDjg93J5nsf4GjwMeErAVd832F7ad4vhsW1S02kfZiab42sTsfW5Sxt25asT'

Update Alias

Update alias in a workspace.

POST /v1/orgs/self/ws/{workspace}/aliases/{alias}

Arguments

workspacerequiredstring(in path)
name of the workspace
aliasrequiredstring(in path)
name of the alias
descriptionoptionalstring
optional description
collectionsrequiredarray
list of fully qualified collection names referenced by alias

Example Request

Example Response

curl --request POST \
    --url https://api.rs2.usw2.rockset.com/v1/orgs/self/ws/commons/aliases/alias \
    -H 'Authorization: ApiKey aB35kDjg93J5nsf4GjwMeErAVd832F7ad4vhsW1S02kfZiab42sTsfW5Sxt25asT' \
  -H 'Content-Type: application/json' \
    -d '{
    "description": "version alias",
    "collections": [
      "commons.foo",
      "prod.demo"
    ]
  }'

Collections

Collection Type

Attributes

created_atoptionalstring

ISO-8601 date

created_byoptionalstring

email of user who created the collection

nameoptionalstring

unique identifer for collection, can contain alphanumeric or dash characters

descriptionoptionalstring

text describing the collection

workspaceoptionalstring

name of the workspace that the collection is in

statusoptionalstring

current status of collection, one of: CREATED, READY, DELETED

sourcesoptionalarray

list of sources from which collection ingests

statsoptional

metrics about the collection

retention_secsoptionalinteger

number of seconds after which data is purged based on event time

field_mappingsoptionalarray

list of mappings applied on all documents in a collection

field_mapping_queryoptional

Field mapping for a collection

clustering_keyoptionalarray

list of clustering fields for a collection

aliasesoptionalarray

list of aliases for a collection

field_schemasoptionalarray

list of field schemas

inverted_index_group_encoding_optionsoptional

inverted index group encoding options

fieldPartitionsoptionalarray

insert_onlyoptionalboolean

Whether the collection is insert only or not

enable_exactly_once_writesoptionalboolean

If true, exactly-once write semantics is enabled.

Example Object

{
  "created_at": "2001-08-28T00:23:41Z",
  "created_by": "hello@rockset.com",
  "name": "global-transactions",
  "description": "transactions from stores worldwide",
  "workspace": "commons",
  "status": "READY",
  "sources": [
    {
      "integration_name": "aws-integration",
      "s3": {
        "access_key": "AKIAIOSFODNN7EXAMPLE",
        "secret_access": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
        "prefix": "prefix/to/keys",
        "pattern": "prefix/to/**/keys/*.format",
        "region": "us-west-2",
        "bucket": "s3://customer-account-info",
        "prefixes": [
          "/transactions",
          "/stores"
        ],
        "format": "none",
        "mappings": [
          {
            "input_path": [
              null
            ],
            "mask": {
              "args": {}
            }
          }
        ]
      },
      "kinesis": {
        "aws_region": "us-east-2",
        "stream_name": "click_stream",
        "dms_primary_key": [
          null
        ]
      },
      "gcs": {
        "bucket": "server-logs",
        "prefix": "prefix/to/keys"
      },
      "redshift": {
        "database": "dev",
        "schema": "common",
        "table_name": "redshift_table_name",
        "incremental_field": "updated_at"
      },
      "dynamodb": {
        "aws_region": "us-east-2",
        "table_name": "dynamodb_table_name",
        "current_status": {
          "initial_dump_completion_percentage": 0.73,
          "state": "PROCESSING_STREAM",
          "stream_last_processed_at": "2019-01-15T21:48:23Z"
        },
        "rcu": 1000,
        "status": {
          "scan_start_time": "2001-08-28T00:23:41Z",
          "scan_end_time": "2001-08-28T00:23:41Z",
          "scan_records_processed": 1000,
          "scan_total_records": 2000,
          "state": "SCANNING_TABLE",
          "stream_last_processed_at": "2019-01-15T21:48:23Z"
        }
      },
      "file_upload": {
        "file_name": "file1.json",
        "file_size": 12345,
        "file_upload_time": "2019-01-15T21:48:23Z"
      },
      "kafka": {
        "kafka_topic_name": "example-topic",
        "status": {
          "state": "ACTIVE",
          "last_consumed_time": "2001-08-28T00:23:41Z",
          "num_documents_processed": 1337,
          "kafka_partitions": [
            {
              "partition_number": 123,
              "partition_offset": 100
            }
          ]
        }
      },
      "mongodb": {
        "database_name": "my_database",
        "collection_name": "my_collection",
        "status": {
          "scan_start_time": "2001-08-28T00:23:41Z",
          "scan_end_time": "2001-08-28T00:23:41Z",
          "scan_records_processed": 1000,
          "scan_total_records": 2000,
          "state": "SCANNING_TABLE",
          "stream_last_insert_processed_at": "2019-01-15T21:48:23Z",
          "stream_last_update_processed_at": "2019-01-15T21:48:23Z",
          "stream_last_delete_processed_at": "2019-01-15T21:48:23Z",
          "stream_records_inserted": 10000,
          "stream_records_updated": 1000,
          "stream_records_deleted": 100
        }
      },
      "status": {
        "state": "INITIALIZING",
        "message": "error 403 forbidden",
        "last_processed_at": "2019-01-15T21:48:23Z",
        "last_processed_item": "/path/to/some/object",
        "total_processed_items": 32849023
      },
      "format_params": {
        "json": true,
        "csv": {
          "firstLineAsColumnNames": true,
          "separator": ",",
          "encoding": "UTF-8",
          "columnNames": [
            "c1",
            "c2",
            "c3"
          ],
          "columnTypes": [
            "BOOLEAN",
            "INTEGER",
            "FLOAT",
            "STRING"
          ],
          "quoteChar": "\"",
          "escapeChar": "\\"
        },
        "xml": {
          "root_tag": "root",
          "encoding": "UTF-8",
          "doc_tag": "row",
          "value_tag": "value",
          "attribute_prefix": "_attr"
        }
      }
    }
  ],
  "stats": {
    "doc_count": 2145,
    "purged_doc_count": 2145,
    "fill_progress": 0.6,
    "last_queried_ms": 1535101119334,
    "last_updated_ms": 1535101094433,
    "total_size": 123456,
    "total_index_size": 123456,
    "row_index_size": 123456,
    "column_index_size": 123456,
    "inverted_index_size": 123456,
    "range_index_size": 123456,
    "purged_doc_size": 123456,
    "bytes_inserted": 123456,
    "bytes_overwritten": 123456
  },
  "retention_secs": 2592000,
  "field_mappings": [
    {
      "name": "myTestMapping",
      "is_drop_all_fields": true,
      "input_fields": [
        {
          "field_name": "address.city.zipcode",
          "if_missing": "['SKIP', 'PASS']",
          "is_drop": true,
          "param": "zip"
        }
      ],
      "output_field": {
        "field_name": "zip_hash",
        "value": "SHA256(:zip)",
        "on_error": "['SKIP', 'FAIL']"
      }
    }
  ],
  "field_mapping_query": {
    "sql": "sql"
  },
  "clustering_key": [
    {
      "field_name": "address.city.zipcode",
      "type": "AUTO",
      "keys": {
        "type": "array",
        "example": "Values of a record to partition on. This is not needed if the partition type is AUTO",
        "description": "The values for partitioning of a field",
        "items": {
          "type": "string"
        }
      }
    }
  ],
  "aliases": [
    {
      "name": "demo",
      "description": "alias referencing collection in workspace",
      "workspace": "commons",
      "creator_email": "xyz@rockset.com",
      "collections": [
        "commons.foo",
        "prod.demo"
      ],
      "state": "CREATED",
      "created_at": "2001-08-28T00:23:41Z",
      "modified_at": "2001-08-28T00:23:42Z"
    }
  ],
  "field_schemas": [
    {
      "field_name": "address.city.zipcode",
      "field_options": "Options to specify whether to build an inverted index  a type index, a range index and a column index on this field"
    }
  ],
  "inverted_index_group_encoding_options": {},
  "fieldPartitions": [
    {
      "field_name": "address.city.zipcode",
      "type": "AUTO",
      "keys": {
        "type": "array",
        "example": "Values of a record to partition on. This is not needed if the partition type is AUTO",
        "description": "The values for partitioning of a field",
        "items": {
          "type": "string"
        }
      }
    }
  ]
}

Create Collection

Create new collection in a workspace.

POST /v1/orgs/self/ws/{workspace}/collections

Arguments

workspacerequiredstring(in path)
name of the workspace
namerequiredstring
unique identifier for collection, can contain alphanumeric or dash characters
descriptionoptionalstring
text describing the collection
sourcesoptionalarray
list of sources from which to ingest data
Show child attributes
retention_secsoptionalinteger
number of seconds after which data is purged, based on event time
time_partition_resolution_secsoptionalinteger
If non-null, the collection will be time partitioned and each partition will be time_partition_resolution_secs wide.
insert_onlyoptionalboolean
If true disallows updates and deletes, but makes indexing more efficient
event_time_infooptionalobject
configuration for event data
Show child attributes
field_mappingsoptionalarray
list of mappings
Show child attributes
field_mapping_queryoptionalobject
Mapping of fields for a collection
Show child attributes
clustering_keyoptionalarray
list of clustering fields
Show child attributes
field_schemasoptionalarray
list of field schemas
Show child attributes
inverted_index_group_encoding_optionsoptionalobject
inverted index group encoding options
Show child attributes

Example Request

Example Response

curl --request POST \
    --url https://api.rs2.usw2.rockset.com/v1/orgs/self/ws/commons/collections \
    -H 'Authorization: ApiKey aB35kDjg93J5nsf4GjwMeErAVd832F7ad4vhsW1S02kfZiab42sTsfW5Sxt25asT' \
  -H 'Content-Type: application/json' \
    -d '{
    "name": "global-transactions",
    "description": "transactions from stores worldwide",
    "sources": [
      {
        "integration_name": "aws-integration",
        "s3": {
          "access_key": "AKIAIOSFODNN7EXAMPLE",
          "secret_access": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
          "prefix": "prefix/to/keys",
          "pattern": "prefix/to/**/keys/*.format",
          "region": "us-west-2",
          "bucket": "s3://customer-account-info",
          "prefixes": [
            "/transactions",
            "/stores"
          ],
          "format": "none",
          "mappings": [
            {
              "input_path": [
                null
              ],
              "mask": {
                "args": {}
              }
            }
          ]
        },
        "kinesis": {
          "aws_region": "us-east-2",
          "stream_name": "click_stream",
          "dms_primary_key": [
            null
          ]
        },
        "gcs": {
          "bucket": "server-logs",
          "prefix": "prefix/to/keys"
        },
        "redshift": {
          "database": "dev",
          "schema": "common",
          "table_name": "redshift_table_name",
          "incremental_field": "updated_at"
        },
        "dynamodb": {
          "aws_region": "us-east-2",
          "table_name": "dynamodb_table_name",
          "current_status": {
            "initial_dump_completion_percentage": 0.73,
            "state": "PROCESSING_STREAM",
            "stream_last_processed_at": "2019-01-15T21:48:23Z"
          },
          "rcu": 1000,
          "status": {
            "scan_start_time": "2001-08-28T00:23:41Z",
            "scan_end_time": "2001-08-28T00:23:41Z",
            "scan_records_processed": 1000,
            "scan_total_records": 2000,
            "state": "SCANNING_TABLE",
            "stream_last_processed_at": "2019-01-15T21:48:23Z"
          }
        },
        "file_upload": {
          "file_name": "file1.json",
          "file_size": 12345,
          "file_upload_time": "2019-01-15T21:48:23Z"
        },
        "kafka": {
          "kafka_topic_name": "example-topic",
          "status": {
            "state": "ACTIVE",
            "last_consumed_time": "2001-08-28T00:23:41Z",
            "num_documents_processed": 1337,
            "kafka_partitions": [
              {
                "partition_number": 123,
                "partition_offset": 100
              }
            ]
          }
        },
        "mongodb": {
          "database_name": "my_database",
          "collection_name": "my_collection",
          "status": {
            "scan_start_time": "2001-08-28T00:23:41Z",
            "scan_end_time": "2001-08-28T00:23:41Z",
            "scan_records_processed": 1000,
            "scan_total_records": 2000,
            "state": "SCANNING_TABLE",
            "stream_last_insert_processed_at": "2019-01-15T21:48:23Z",
            "stream_last_update_processed_at": "2019-01-15T21:48:23Z",
            "stream_last_delete_processed_at": "2019-01-15T21:48:23Z",
            "stream_records_inserted": 10000,
            "stream_records_updated": 1000,
            "stream_records_deleted": 100
          }
        },
        "status": {
          "state": "INITIALIZING",
          "message": "error 403 forbidden",
          "last_processed_at": "2019-01-15T21:48:23Z",
          "last_processed_item": "/path/to/some/object",
          "total_processed_items": 32849023
        },
        "format_params": {
          "json": true,
          "csv": {
            "firstLineAsColumnNames": true,
            "separator": ",",
            "encoding": "UTF-8",
            "columnNames": [
              "c1",
              "c2",
              "c3"
            ],
            "columnTypes": [
              "BOOLEAN",
              "INTEGER",
              "FLOAT",
              "STRING"
            ],
            "quoteChar": "\"",
            "escapeChar": "\\"
          },
          "xml": {
            "root_tag": "root",
            "encoding": "UTF-8",
            "doc_tag": "row",
            "value_tag": "value",
            "attribute_prefix": "_attr"
          }
        }
      }
    ],
    "retention_secs": 1000000,
    "event_time_info": {
      "field": "timestamp",
      "format": "seconds_since_epoch",
      "time_zone": "UTC"
    },
    "field_mappings": [
      {
        "name": "myTestMapping",
        "is_drop_all_fields": true,
        "input_fields": [
          {
            "field_name": "address.city.zipcode",
            "if_missing": "['\''SKIP'\'', '\''PASS'\'']",
            "is_drop": true,
            "param": "zip"
          }
        ],
        "output_field": {
          "field_name": "zip_hash",
          "value": "SHA256(:zip)",
          "on_error": "['\''SKIP'\'', '\''FAIL'\'']"
        }
      }
    ],
    "field_mapping_query": {
      "sql": "sql"
    },
    "clustering_key": [
      {
        "field_name": "address.city.zipcode",
        "type": "AUTO",
        "keys": {
          "type": "array",
          "example": "Values of a record to partition on. This is not needed if the partition type is AUTO",
          "description": "The values for partitioning of a field",
          "items": {
            "type": "string"
          }
        }
      }
    ],
    "field_schemas": [
      {
        "field_name": "address.city.zipcode",
        "field_options": "Options to specify whether to build an inverted index  a type index, a range index and a column index on this field"
      }
    ],
    "inverted_index_group_encoding_options": {}
  }'

Delete Collection

Delete a collection and all its documents from Rockset.

DELETE /v1/orgs/self/ws/{workspace}/collections/{collection}

Arguments

workspacerequiredstring(in path)
name of the workspace
collectionrequiredstring(in path)
name of the collection

Example Request

Example Response

curl --request DELETE \
    --url https://api.rs2.usw2.rockset.com/v1/orgs/self/ws/commons/collections/customers \
    -H 'Authorization: ApiKey aB35kDjg93J5nsf4GjwMeErAVd832F7ad4vhsW1S02kfZiab42sTsfW5Sxt25asT'

List Collections

Retrieve all collections in an organization.

GET /v1/orgs/self/collections

Arguments

No arguments.

Example Request

Example Response

curl --request GET \
    --url https://api.rs2.usw2.rockset.com/v1/orgs/self/collections \
    -H 'Authorization: ApiKey aB35kDjg93J5nsf4GjwMeErAVd832F7ad4vhsW1S02kfZiab42sTsfW5Sxt25asT'

List Collections in Workspace

Retrieve all collections in a workspace.

GET /v1/orgs/self/ws/{workspace}/collections

Arguments

workspacerequiredstring(in path)
name of the workspace

Example Request

Example Response

curl --request GET \
    --url https://api.rs2.usw2.rockset.com/v1/orgs/self/ws/commons/collections \
    -H 'Authorization: ApiKey aB35kDjg93J5nsf4GjwMeErAVd832F7ad4vhsW1S02kfZiab42sTsfW5Sxt25asT'

Retrieve Collection

Get details about a collection.

GET /v1/orgs/self/ws/{workspace}/collections/{collection}

Arguments

workspacerequiredstring(in path)
name of the workspace
collectionrequiredstring(in path)
name of the collection

Example Request

Example Response

curl --request GET \
    --url https://api.rs2.usw2.rockset.com/v1/orgs/self/ws/commons/collections/customers \
    -H 'Authorization: ApiKey aB35kDjg93J5nsf4GjwMeErAVd832F7ad4vhsW1S02kfZiab42sTsfW5Sxt25asT'

Integrations

Integration Type

Integrations that can be associated with data sources to create collections. Only one type of integration may be specified.

Attributes

nameoptionalstring

descriptive label and unique identifier

descriptionoptionalstring

longer explanation for the integration

collectionsoptionalarray

list of collections that use the integration

created_byoptionalstring

email of user who created the integration

created_atoptionalstring

ISO-8601 date

s3optional

Amazon S3 details, must have one of aws_access_key or aws_role

kinesisoptional

Amazon Kinesis details, must have one of aws_access_key or aws_role

dynamodboptional

Amazon DynamoDB details, must have one of aws_access_key or aws_role

gcsoptional

GCS details

segmentoptional

Segment details

kafkaoptional

Kafka details

mongodboptional

MongoDb details

Example Object

{
  "name": "event-logs",
  "description": "AWS account with event data for the data science team.",
  "collections": [
    {
      "created_at": "2001-08-28T00:23:41Z",
      "created_by": "hello@rockset.com",
      "name": "global-transactions",
      "description": "transactions from stores worldwide",
      "workspace": "commons",
      "status": "READY",
      "sources": [
        {
          "integration_name": "aws-integration",
          "s3": {
            "access_key": "AKIAIOSFODNN7EXAMPLE",
            "secret_access": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
            "prefix": "prefix/to/keys",
            "pattern": "prefix/to/**/keys/*.format",
            "region": "us-west-2",
            "bucket": "s3://customer-account-info",
            "prefixes": [
              "/transactions",
              "/stores"
            ],
            "format": "none",
            "mappings": [
              {
                "input_path": [
                  null
                ],
                "mask": {
                  "args": {}
                }
              }
            ]
          },
          "kinesis": {
            "aws_region": "us-east-2",
            "stream_name": "click_stream",
            "dms_primary_key": [
              null
            ]
          },
          "gcs": {
            "bucket": "server-logs",
            "prefix": "prefix/to/keys"
          },
          "redshift": {
            "database": "dev",
            "schema": "common",
            "table_name": "redshift_table_name",
            "incremental_field": "updated_at"
          },
          "dynamodb": {
            "aws_region": "us-east-2",
            "table_name": "dynamodb_table_name",
            "current_status": {
              "initial_dump_completion_percentage": 0.73,
              "state": "PROCESSING_STREAM",
              "stream_last_processed_at": "2019-01-15T21:48:23Z"
            },
            "rcu": 1000,
            "status": {
              "scan_start_time": "2001-08-28T00:23:41Z",
              "scan_end_time": "2001-08-28T00:23:41Z",
              "scan_records_processed": 1000,
              "scan_total_records": 2000,
              "state": "SCANNING_TABLE",
              "stream_last_processed_at": "2019-01-15T21:48:23Z"
            }
          },
          "file_upload": {
            "file_name": "file1.json",
            "file_size": 12345,
            "file_upload_time": "2019-01-15T21:48:23Z"
          },
          "kafka": {
            "kafka_topic_name": "example-topic",
            "status": {
              "state": "ACTIVE",
              "last_consumed_time": "2001-08-28T00:23:41Z",
              "num_documents_processed": 1337,
              "kafka_partitions": [
                {
                  "partition_number": 123,
                  "partition_offset": 100
                }
              ]
            }
          },
          "mongodb": {
            "database_name": "my_database",
            "collection_name": "my_collection",
            "status": {
              "scan_start_time": "2001-08-28T00:23:41Z",
              "scan_end_time": "2001-08-28T00:23:41Z",
              "scan_records_processed": 1000,
              "scan_total_records": 2000,
              "state": "SCANNING_TABLE",
              "stream_last_insert_processed_at": "2019-01-15T21:48:23Z",
              "stream_last_update_processed_at": "2019-01-15T21:48:23Z",
              "stream_last_delete_processed_at": "2019-01-15T21:48:23Z",
              "stream_records_inserted": 10000,
              "stream_records_updated": 1000,
              "stream_records_deleted": 100
            }
          },
          "status": {
            "state": "INITIALIZING",
            "message": "error 403 forbidden",
            "last_processed_at": "2019-01-15T21:48:23Z",
            "last_processed_item": "/path/to/some/object",
            "total_processed_items": 32849023
          },
          "format_params": {
            "json": true,
            "csv": {
              "firstLineAsColumnNames": true,
              "separator": ",",
              "encoding": "UTF-8",
              "columnNames": [
                "c1",
                "c2",
                "c3"
              ],
              "columnTypes": [
                "BOOLEAN",
                "INTEGER",
                "FLOAT",
                "STRING"
              ],
              "quoteChar": "\"",
              "escapeChar": "\\"
            },
            "xml": {
              "root_tag": "root",
              "encoding": "UTF-8",
              "doc_tag": "row",
              "value_tag": "value",
              "attribute_prefix": "_attr"
            }
          }
        }
      ],
      "stats": {
        "doc_count": 2145,
        "purged_doc_count": 2145,
        "fill_progress": 0.6,
        "last_queried_ms": 1535101119334,
        "last_updated_ms": 1535101094433,
        "total_size": 123456,
        "total_index_size": 123456,
        "row_index_size": 123456,
        "column_index_size": 123456,
        "inverted_index_size": 123456,
        "range_index_size": 123456,
        "purged_doc_size": 123456,
        "bytes_inserted": 123456,
        "bytes_overwritten": 123456
      },
      "retention_secs": 2592000,
      "field_mappings": [
        {
          "name": "myTestMapping",
          "is_drop_all_fields": true,
          "input_fields": [
            {
              "field_name": "address.city.zipcode",
              "if_missing": "['SKIP', 'PASS']",
              "is_drop": true,
              "param": "zip"
            }
          ],
          "output_field": {
            "field_name": "zip_hash",
            "value": "SHA256(:zip)",
            "on_error": "['SKIP', 'FAIL']"
          }
        }
      ],
      "field_mapping_query": {
        "sql": "sql"
      },
      "clustering_key": [
        {
          "field_name": "address.city.zipcode",
          "type": "AUTO",
          "keys": {
            "type": "array",
            "example": "Values of a record to partition on. This is not needed if the partition type is AUTO",
            "description": "The values for partitioning of a field",
            "items": {
              "type": "string"
            }
          }
        }
      ],
      "aliases": [
        {
          "name": "demo",
          "description": "alias referencing collection in workspace",
          "workspace": "commons",
          "creator_email": "xyz@rockset.com",
          "collections": [
            "commons.foo",
            "prod.demo"
          ],
          "state": "CREATED",
          "created_at": "2001-08-28T00:23:41Z",
          "modified_at": "2001-08-28T00:23:42Z"
        }
      ],
      "field_schemas": [
        {
          "field_name": "address.city.zipcode",
          "field_options": "Options to specify whether to build an inverted index  a type index, a range index and a column index on this field"
        }
      ],
      "inverted_index_group_encoding_options": {},
      "fieldPartitions": [
        {
          "field_name": "address.city.zipcode",
          "type": "AUTO",
          "keys": {
            "type": "array",
            "example": "Values of a record to partition on. This is not needed if the partition type is AUTO",
            "description": "The values for partitioning of a field",
            "items": {
              "type": "string"
            }
          }
        }
      ]
    }
  ],
  "created_by": "hello@rockset.com",
  "created_at": "2001-08-28T00:23:41Z",
  "s3": {
    "aws_access_key": {
      "aws_access_key_id": "AKIAIOSFODNN7EXAMPLE",
      "aws_secret_access_key": "wJal...."
    },
    "aws_role": {
      "aws_role_arn": "arn:aws:iam::2378964092:role/rockset-role"
    }
  },
  "kinesis": {
    "aws_access_key": {
      "aws_access_key_id": "AKIAIOSFODNN7EXAMPLE",
      "aws_secret_access_key": "wJal...."
    },
    "aws_role": {
      "aws_role_arn": "arn:aws:iam::2378964092:role/rockset-role"
    }
  },
  "dynamodb": {
    "aws_access_key": {
      "aws_access_key_id": "AKIAIOSFODNN7EXAMPLE",
      "aws_secret_access_key": "wJal...."
    },
    "aws_role": {
      "aws_role_arn": "arn:aws:iam::2378964092:role/rockset-role"
    }
  },
  "gcs": {
    "gcp_service_account": {}
  },
  "segment": {},
  "kafka": {
    "kafka_topic_names": [
      null
    ],
    "source_status_by_topic": {
      "type": "object",
      "example": "topic-a:DORMANT",
      "description": "The status of the Kafka source by topic",
      "readOnly": true,
      "additionalProperties": {
        "$ref": "#/definitions/StatusKafka"
      }
    },
    "kafka_data_format": "json",
    "security_config": {}
  },
  "mongodb": {
    "connection_uri": "mongodb+srv://<username>:<password>@server.example.com/"
  }
}

Create Integration

Create a new integration.

POST /v1/orgs/self/integrations

Arguments

namerequiredstring
descriptive label
descriptionoptionalstring
longer explanation for the integration
s3optionalobject
Amazon S3 details, must have one of aws_access_key or aws_role
Show child attributes
kinesisoptionalobject
Amazon Kinesis details, must have one of aws_access_key or aws_role
Show child attributes
dynamodboptionalobject
Amazon DynamoDB details, must have one of aws_access_key or aws_role
Show child attributes
redshiftoptionalobject
Amazon Redshift details
Show child attributes
gcsoptionalobject
GCS details
Show child attributes
segmentoptionalobject
Show child attributes
kafkaoptionalobject
Show child attributes
mongodboptionalobject
MongoDb details
Show child attributes

Example Request

Example Response

curl --request POST \
    --url https://api.rs2.usw2.rockset.com/v1/orgs/self/integrations \
    -H 'Authorization: ApiKey aB35kDjg93J5nsf4GjwMeErAVd832F7ad4vhsW1S02kfZiab42sTsfW5Sxt25asT' \
  -H 'Content-Type: application/json' \
    -d '{
    "name": "event-logs",
    "description": "AWS account with event data for the data science team.",
    "s3": {
      "aws_access_key": {
        "aws_access_key_id": "AKIAIOSFODNN7EXAMPLE",
        "aws_secret_access_key": "wJal...."
      },
      "aws_role": {
        "aws_role_arn": "arn:aws:iam::2378964092:role/rockset-role"
      }
    },
    "kinesis": {
      "aws_access_key": {
        "aws_access_key_id": "AKIAIOSFODNN7EXAMPLE",
        "aws_secret_access_key": "wJal...."
      },
      "aws_role": {
        "aws_role_arn": "arn:aws:iam::2378964092:role/rockset-role"
      }
    },
    "dynamodb": {
      "aws_access_key": {
        "aws_access_key_id": "AKIAIOSFODNN7EXAMPLE",
        "aws_secret_access_key": "wJal...."
      },
      "aws_role": {
        "aws_role_arn": "arn:aws:iam::2378964092:role/rockset-role"
      }
    },
    "redshift": {
      "aws_access_key": {
        "aws_access_key_id": "AKIAIOSFODNN7EXAMPLE",
        "aws_secret_access_key": "wJal...."
      },
      "username": "awsuser",
      "password": "pswd....",
      "host": "test.yuyugt.us-west-2.redshift.amazonaws.com",
      "port": 5439,
      "s3_bucket_path": "s3://redshift-unload"
    },
    "gcs": {
      "gcp_service_account": {}
    },
    "segment": {},
    "kafka": {
      "kafka_topic_names": [
        null
      ],
      "source_status_by_topic": {
        "type": "object",
        "example": "topic-a:DORMANT",
        "description": "The status of the Kafka source by topic",
        "readOnly": true,
        "additionalProperties": {
          "$ref": "#/definitions/StatusKafka"
        }
      },
      "kafka_data_format": "json",
      "security_config": {}
    },
    "mongodb": {
      "connection_uri": "mongodb+srv://<username>:<password>@server.example.com/"
    }
  }'

Delete Integration

Remove an integration.

DELETE /v1/orgs/self/integrations/{integration}

Arguments

integrationrequiredstring(in path)
name of the integration

Example Request

Example Response

curl --request DELETE \
    --url https://api.rs2.usw2.rockset.com/v1/orgs/self/integrations/my-aws-creds \
    -H 'Authorization: ApiKey aB35kDjg93J5nsf4GjwMeErAVd832F7ad4vhsW1S02kfZiab42sTsfW5Sxt25asT'

List Integrations

List all integrations in an organization.

GET /v1/orgs/self/integrations

Arguments

No arguments.

Example Request

Example Response

curl --request GET \
    --url https://api.rs2.usw2.rockset.com/v1/orgs/self/integrations \
    -H 'Authorization: ApiKey aB35kDjg93J5nsf4GjwMeErAVd832F7ad4vhsW1S02kfZiab42sTsfW5Sxt25asT'

Retrieve Integration

Retrieve information about a single integration.

GET /v1/orgs/self/integrations/{integration}

Arguments

integrationrequiredstring(in path)
name of the integration

Example Request

Example Response

curl --request GET \
    --url https://api.rs2.usw2.rockset.com/v1/orgs/self/integrations/my-aws-creds \
    -H 'Authorization: ApiKey aB35kDjg93J5nsf4GjwMeErAVd832F7ad4vhsW1S02kfZiab42sTsfW5Sxt25asT'

Query Lambdas

QueryLambda Type

Attributes

workspaceoptionalstring

workspace of this Query Lambda

last_updated_byoptionalstring

user that created this Query Lambda

last_updatedoptionalstring

ISO-8601 date of when Query Lambda was last updated

nameoptionalstring

Query Lambda name

version_countoptionalinteger

number of Query Lambda versions

collectionsoptionalarray

collections/aliases queried by underlying SQL query

latest_versionoptional

Query Lambda version details for most recently created version

Example Object

{
  "workspace": "commons",
  "last_updated_by": "..@rockset.com",
  "last_updated": "2001-08-28T00:23:41Z",
  "name": "myQuery",
  "version_count": 1,
  "collections": [
    null
  ],
  "latest_version": {
    "workspace": "commons",
    "created_by": "..@rockset.com",
    "created_at": "2001-08-28T00:23:41Z",
    "name": "myQuery",
    "version": "acb99feg92bcaf",
    "description": "production version foo",
    "sql": {
      "query": "SELECT 'Foo'",
      "default_parameters": [
        {
          "name": "_id",
          "type": "string",
          "value": "85beb391"
        }
      ]
    },
    "collections": [
      null
    ],
    "state": "ACTIVE",
    "stats": {
      "last_executed": "2001-08-28T00:23:41Z",
      "last_executed_by": "...@rockset.com",
      "last_execution_error": "2001-08-28T00:23:41Z",
      "last_execution_error_message": "[error message]"
    }
  }
}

Create Query Lambda

Create a Query Lambda in given workspace.

POST /v1/orgs/self/ws/{workspace}/lambdas

Arguments

workspacerequiredstring(in path)
name of the workspace
namerequiredstring
Query Lambda name
descriptionoptionalstring
optional description
sqlrequiredobject
Query Lambda SQL query
Show child attributes

Example Request

Example Response

curl --request POST \
    --url https://api.rs2.usw2.rockset.com/v1/orgs/self/ws/commons/lambdas \
    -H 'Authorization: ApiKey aB35kDjg93J5nsf4GjwMeErAVd832F7ad4vhsW1S02kfZiab42sTsfW5Sxt25asT' \
  -H 'Content-Type: application/json' \
    -d '{
    "name": "myQueryLambda",
    "description": "production version foo",
    "sql": {
      "query": "SELECT '\''Foo'\''",
      "default_parameters": [
        {
          "name": "_id",
          "type": "string",
          "value": "85beb391"
        }
      ]
    }
  }'

Create Query Lambda Tag

Create a tag for a specific Query Lambda version, or update that tag if it already exists.

POST /v1/orgs/self/ws/{workspace}/lambdas/{queryLambda}/tags

Arguments

workspacerequiredstring(in path)
name of the workspace
queryLambdarequiredstring(in path)
name of the Query Lambda
tag_namerequiredstring
name of Query Lambda tag
versionrequiredstring
hash identifying a Query Lambda tag

Example Request

Example Response

curl --request POST \
    --url https://api.rs2.usw2.rockset.com/v1/orgs/self/ws/commons/lambdas/queryLambda/tags \
    -H 'Authorization: ApiKey aB35kDjg93J5nsf4GjwMeErAVd832F7ad4vhsW1S02kfZiab42sTsfW5Sxt25asT' \
  -H 'Content-Type: application/json' \
    -d '{
    "tag_name": "production",
    "version": "123ABC"
  }'

Delete Query Lambda

Delete a Query Lambda.

DELETE /v1/orgs/self/ws/{workspace}/lambdas/{queryLambda}

Arguments

workspacerequiredstring(in path)
name of the workspace
queryLambdarequiredstring(in path)
name of the Query Lambda

Example Request

Example Response

curl --request DELETE \
    --url https://api.rs2.usw2.rockset.com/v1/orgs/self/ws/commons/lambdas/queryLambda \
    -H 'Authorization: ApiKey aB35kDjg93J5nsf4GjwMeErAVd832F7ad4vhsW1S02kfZiab42sTsfW5Sxt25asT'

Delete Query Lambda Version

Delete a Query Lambda version.

DELETE /v1/orgs/self/ws/{workspace}/lambdas/{queryLambda}/version/{version}

Arguments

workspacerequiredstring(in path)
name of the workspace
queryLambdarequiredstring(in path)
name of the Query Lambda
versionrequiredstring(in path)
version

Example Request

Example Response

curl --request DELETE \
    --url https://api.rs2.usw2.rockset.com/v1/orgs/self/ws/commons/lambdas/queryLambda/version/version \
    -H 'Authorization: ApiKey aB35kDjg93J5nsf4GjwMeErAVd832F7ad4vhsW1S02kfZiab42sTsfW5Sxt25asT'

Execute Query Lambda By Tag

Execute the Query Lambda version associated with a given tag.

POST /v1/orgs/self/ws/{workspace}/lambdas/{queryLambda}/tags/{tag}

Arguments

workspacerequiredstring(in path)
name of the workspace
queryLambdarequiredstring(in path)
name of the Query Lambda
tagrequiredstring(in path)
tag
parametersoptionalarray
list of named parameters
Show child attributes
default_row_limitoptionalinteger
Row limit to use if no limit specified in the SQL query text
generate_warningsoptionalboolean
Whether to generate warnings
paginateoptionalboolean
Flag to paginate and store the results of this query for later / sequential retrieval.
initial_paginate_response_doc_countoptionalinteger
Number of documents to return in addition to paginating for this query call. Only relevant if paginate flag is also set.

Example Request

Example Response

curl --request POST \
    --url https://api.rs2.usw2.rockset.com/v1/orgs/self/ws/commons/lambdas/queryLambda/tags/tag \
    -H 'Authorization: ApiKey aB35kDjg93J5nsf4GjwMeErAVd832F7ad4vhsW1S02kfZiab42sTsfW5Sxt25asT' \
  -H 'Content-Type: application/json' \
    -d '{
    "parameters": [
      {
        "name": "_id",
        "type": "string",
        "value": "85beb391"
      }
    ]
  }'

Execute Query Lambda By Version

Execute a particular version of a Query Lambda.

POST /v1/orgs/self/ws/{workspace}/lambdas/{queryLambda}/versions/{version}

Arguments

workspacerequiredstring(in path)
name of the workspace
queryLambdarequiredstring(in path)
name of the Query Lambda
versionrequiredstring(in path)
version
parametersoptionalarray
list of named parameters
Show child attributes
default_row_limitoptionalinteger
Row limit to use if no limit specified in the SQL query text
generate_warningsoptionalboolean
Whether to generate warnings
paginateoptionalboolean
Flag to paginate and store the results of this query for later / sequential retrieval.
initial_paginate_response_doc_countoptionalinteger
Number of documents to return in addition to paginating for this query call. Only relevant if paginate flag is also set.

Example Request

Example Response

curl --request POST \
    --url https://api.rs2.usw2.rockset.com/v1/orgs/self/ws/commons/lambdas/queryLambda/versions/version \
    -H 'Authorization: ApiKey aB35kDjg93J5nsf4GjwMeErAVd832F7ad4vhsW1S02kfZiab42sTsfW5Sxt25asT' \
  -H 'Content-Type: application/json' \
    -d '{
    "parameters": [
      {
        "name": "_id",
        "type": "string",
        "value": "85beb391"
      }
    ]
  }'

List Query Lambda Tags

List all tags associated with a Query Lambda

GET /v1/orgs/self/ws/{workspace}/lambdas/{queryLambda}/tags

Arguments

workspacerequiredstring(in path)
name of the workspace
queryLambdarequiredstring(in path)
name of the Query Lambda

Example Request

Example Response

curl --request GET \
    --url https://api.rs2.usw2.rockset.com/v1/orgs/self/ws/commons/lambdas/queryLambda/tags \
    -H 'Authorization: ApiKey aB35kDjg93J5nsf4GjwMeErAVd832F7ad4vhsW1S02kfZiab42sTsfW5Sxt25asT'

List Query Lambda Versions

List all versions of a Query Lambda.

GET /v1/orgs/self/ws/{workspace}/lambdas/{queryLambda}/versions

Arguments

workspacerequiredstring(in path)
name of the workspace
queryLambdarequiredstring(in path)
name of the Query Lambda

Example Request

Example Response

curl --request GET \
    --url https://api.rs2.usw2.rockset.com/v1/orgs/self/ws/commons/lambdas/queryLambda/versions \
    -H 'Authorization: ApiKey aB35kDjg93J5nsf4GjwMeErAVd832F7ad4vhsW1S02kfZiab42sTsfW5Sxt25asT'

List Query Lambdas

List all Query Lambdas in an organization.

GET /v1/orgs/self/lambdas

Arguments

No arguments.

Example Request

Example Response

curl --request GET \
    --url https://api.rs2.usw2.rockset.com/v1/orgs/self/lambdas \
    -H 'Authorization: ApiKey aB35kDjg93J5nsf4GjwMeErAVd832F7ad4vhsW1S02kfZiab42sTsfW5Sxt25asT'

List Query Lambdas in Workspace

List all Query Lambdas under given workspace.

GET /v1/orgs/self/ws/{workspace}/lambdas

Arguments

workspacerequiredstring(in path)
name of the workspace

Example Request

Example Response

curl --request GET \
    --url https://api.rs2.usw2.rockset.com/v1/orgs/self/ws/commons/lambdas \
    -H 'Authorization: ApiKey aB35kDjg93J5nsf4GjwMeErAVd832F7ad4vhsW1S02kfZiab42sTsfW5Sxt25asT'

Retrieve Query Lambda Tag

Retrieve the Query Lambda version associated with a given tag.

GET /v1/orgs/self/ws/{workspace}/lambdas/{queryLambda}/tags/{tag}

Arguments

workspacerequiredstring(in path)
name of the workspace
queryLambdarequiredstring(in path)
name of the Query Lambda
tagrequiredstring(in path)
name of the tag

Example Request

Example Response

curl --request GET \
    --url https://api.rs2.usw2.rockset.com/v1/orgs/self/ws/commons/lambdas/queryLambda/tags/tag \
    -H 'Authorization: ApiKey aB35kDjg93J5nsf4GjwMeErAVd832F7ad4vhsW1S02kfZiab42sTsfW5Sxt25asT'

Retrieve Query Lambda Version

Retrieve details for a specified version of a Query Lambda.

GET /v1/orgs/self/ws/{workspace}/lambdas/{queryLambda}/versions/{version}

Arguments

workspacerequiredstring(in path)
name of the workspace
queryLambdarequiredstring(in path)
name of the Query Lambda
versionrequiredstring(in path)
version

Example Request

Example Response

curl --request GET \
    --url https://api.rs2.usw2.rockset.com/v1/orgs/self/ws/commons/lambdas/queryLambda/versions/version \
    -H 'Authorization: ApiKey aB35kDjg93J5nsf4GjwMeErAVd832F7ad4vhsW1S02kfZiab42sTsfW5Sxt25asT'

Update Query Lambda

Create a new version of a Query Lambda in given workspace.

POST /v1/orgs/self/ws/{workspace}/lambdas/{queryLambda}/versions

Arguments

workspacerequiredstring(in path)
name of the workspace
queryLambdarequiredstring(in path)
name of the Query Lambda
descriptionoptionalstring
optional description
sqloptionalobject
Query Lambda SQL query
Show child attributes
createoptionalboolean

Example Request

Example Response

curl --request POST \
    --url https://api.rs2.usw2.rockset.com/v1/orgs/self/ws/commons/lambdas/queryLambda/versions \
    -H 'Authorization: ApiKey aB35kDjg93J5nsf4GjwMeErAVd832F7ad4vhsW1S02kfZiab42sTsfW5Sxt25asT' \
  -H 'Content-Type: application/json' \
    -d '{
    "description": "production version foo",
    "sql": {
      "query": "SELECT '\''Foo'\''",
      "default_parameters": [
        {
          "name": "_id",
          "type": "string",
          "value": "85beb391"
        }
      ]
    }
  }'

Users

User Type

Attributes

created_atoptionalstring

ISO-8601 date

emailoptionalstring

user email

first_nameoptionalstring

user first name

last_nameoptionalstring

user last name

rolesoptionalarray

List of roles for a given user

stateoptionalstring

state of user - NEW / ACTIVE

Example Object

{
  "created_at": "2001-08-28T00:23:41Z",
  "email": "hello@rockset.com",
  "first_name": "John",
  "last_name": "Doe",
  "roles": [
    "admin",
    "member",
    "read-only"
  ],
  "state": "ACTIVE"
}

Create User

Create a new user for an organization.

POST /v1/orgs/self/users

Arguments

emailrequiredstring
user email, must be unique
rolesrequiredarray
List of roles for a given user

Example Request

Example Response

curl --request POST \
    --url https://api.rs2.usw2.rockset.com/v1/orgs/self/users \
    -H 'Authorization: ApiKey aB35kDjg93J5nsf4GjwMeErAVd832F7ad4vhsW1S02kfZiab42sTsfW5Sxt25asT' \
  -H 'Content-Type: application/json' \
    -d '{
    "email": "hello@rockset.com",
    "roles": [
      "admin",
      "member",
      "read-only"
    ]
  }'

Delete User

Delete a user from an organization.

DELETE /v1/orgs/self/users/{user}

Arguments

userrequiredstring(in path)
user email

Example Request

Example Response

curl --request DELETE \
    --url https://api.rs2.usw2.rockset.com/v1/orgs/self/users/admin@me.com \
    -H 'Authorization: ApiKey aB35kDjg93J5nsf4GjwMeErAVd832F7ad4vhsW1S02kfZiab42sTsfW5Sxt25asT'

Get all notification preferences

Get all notification preferences.

GET /v1/orgs/self/users/self/preferences

Arguments

No arguments.

Example Request

Example Response

curl --request GET \
    --url https://api.rs2.usw2.rockset.com/v1/orgs/self/users/self/preferences \
    -H 'Authorization: ApiKey aB35kDjg93J5nsf4GjwMeErAVd832F7ad4vhsW1S02kfZiab42sTsfW5Sxt25asT'

List Users

Retrieve all users for an organization.

GET /v1/orgs/self/users

Arguments

No arguments.

Example Request

Example Response

curl --request GET \
    --url https://api.rs2.usw2.rockset.com/v1/orgs/self/users \
    -H 'Authorization: ApiKey aB35kDjg93J5nsf4GjwMeErAVd832F7ad4vhsW1S02kfZiab42sTsfW5Sxt25asT'

Retrieve Current User

Retrieve currently authenticated user.

GET /v1/orgs/self/users/self

Arguments

No arguments.

Example Request

Example Response

curl --request GET \
    --url https://api.rs2.usw2.rockset.com/v1/orgs/self/users/self \
    -H 'Authorization: ApiKey aB35kDjg93J5nsf4GjwMeErAVd832F7ad4vhsW1S02kfZiab42sTsfW5Sxt25asT'

Retrieve User

Retrieve user by email.

GET /v1/orgs/self/users/{user}

Arguments

userrequiredstring(in path)
user email

Example Request

Example Response

curl --request GET \
    --url https://api.rs2.usw2.rockset.com/v1/orgs/self/users/admin@me.com \
    -H 'Authorization: ApiKey aB35kDjg93J5nsf4GjwMeErAVd832F7ad4vhsW1S02kfZiab42sTsfW5Sxt25asT'

Update notification preferences

Update notification preference.

POST /v1/orgs/self/users/self/preferences

Arguments

dataoptionalarray
List of notification preferences
Show child attributes

Example Request

Example Response

curl --request POST \
    --url https://api.rs2.usw2.rockset.com/v1/orgs/self/users/self/preferences \
    -H 'Authorization: ApiKey aB35kDjg93J5nsf4GjwMeErAVd832F7ad4vhsW1S02kfZiab42sTsfW5Sxt25asT' \
  -H 'Content-Type: application/json' \
    -d '{
    "data": [
      {
        "notificationType": "create_apikey"
      }
    ]
  }'

Views

Create View

Create a view

POST /v1/orgs/self/ws/{workspace}/views

Arguments

workspacerequiredstring(in path)
name of the workspace
namerequiredstring
View name
descriptionoptionalstring
optional description
queryrequiredstring
SQL for this view

Example Request

Example Response

curl --request POST \
    --url https://api.rs2.usw2.rockset.com/v1/orgs/self/ws/commons/views \
    -H 'Authorization: ApiKey aB35kDjg93J5nsf4GjwMeErAVd832F7ad4vhsW1S02kfZiab42sTsfW5Sxt25asT' \
  -H 'Content-Type: application/json' \
    -d '{
    "name": "myAwesomeView",
    "description": "view of awesome collection",
    "query": "SELECT * FROM foo"
  }'

Delete View

Delete a view

DELETE /v1/orgs/self/ws/{workspace}/views/{view}

Arguments

workspacerequiredstring(in path)
name of the workspace
viewrequiredstring(in path)
name of the view

Example Request

Example Response

curl --request DELETE \
    --url https://api.rs2.usw2.rockset.com/v1/orgs/self/ws/commons/views/view \
    -H 'Authorization: ApiKey aB35kDjg93J5nsf4GjwMeErAVd832F7ad4vhsW1S02kfZiab42sTsfW5Sxt25asT'

List Views

Retrieve all views in an organization

GET /v1/orgs/self/views

Arguments

No arguments.

Example Request

Example Response

curl --request GET \
    --url https://api.rs2.usw2.rockset.com/v1/orgs/self/views \
    -H 'Authorization: ApiKey aB35kDjg93J5nsf4GjwMeErAVd832F7ad4vhsW1S02kfZiab42sTsfW5Sxt25asT'

List Views in Workspace

Retrieve all views in a workspace.

GET /v1/orgs/self/ws/{workspace}/views

Arguments

workspacerequiredstring(in path)
name of the workspace

Example Request

Example Response

curl --request GET \
    --url https://api.rs2.usw2.rockset.com/v1/orgs/self/ws/commons/views \
    -H 'Authorization: ApiKey aB35kDjg93J5nsf4GjwMeErAVd832F7ad4vhsW1S02kfZiab42sTsfW5Sxt25asT'

Retrieve View

Get details about a view

GET /v1/orgs/self/ws/{workspace}/views/{view}

Arguments

workspacerequiredstring(in path)
name of the workspace
viewrequiredstring(in path)
name of the view

Example Request

Example Response

curl --request GET \
    --url https://api.rs2.usw2.rockset.com/v1/orgs/self/ws/commons/views/view \
    -H 'Authorization: ApiKey aB35kDjg93J5nsf4GjwMeErAVd832F7ad4vhsW1S02kfZiab42sTsfW5Sxt25asT'

Update View

Update a view

POST /v1/orgs/self/ws/{workspace}/views/{view}

Arguments

workspacerequiredstring(in path)
name of the workspace
viewrequiredstring(in path)
name of the view
descriptionoptionalstring
optional description
queryrequiredstring
SQL for this view

Example Request

Example Response

curl --request POST \
    --url https://api.rs2.usw2.rockset.com/v1/orgs/self/ws/commons/views/view \
    -H 'Authorization: ApiKey aB35kDjg93J5nsf4GjwMeErAVd832F7ad4vhsW1S02kfZiab42sTsfW5Sxt25asT' \
  -H 'Content-Type: application/json' \
    -d '{
    "description": "view of awesome collection",
    "query": "SELECT * FROM foo"
  }'

Virtual Instances

List Virtual Instances

Retrieve all virtual instances in an organization.

GET /v1/orgs/self/virtualinstances

Arguments

No arguments.

Example Request

Example Response

curl --request GET \
    --url https://api.rs2.usw2.rockset.com/v1/orgs/self/virtualinstances \
    -H 'Authorization: ApiKey aB35kDjg93J5nsf4GjwMeErAVd832F7ad4vhsW1S02kfZiab42sTsfW5Sxt25asT'

Retrieve Virtual Instance

Get details about a virtual instance.

GET /v1/orgs/self/virtualinstances/{virtualInstanceId}

Arguments

virtualInstanceIdrequiredstring(in path)
uuid of the virtual instance

Example Request

Example Response

curl --request GET \
    --url https://api.rs2.usw2.rockset.com/v1/orgs/self/virtualinstances/virtualInstanceId \
    -H 'Authorization: ApiKey aB35kDjg93J5nsf4GjwMeErAVd832F7ad4vhsW1S02kfZiab42sTsfW5Sxt25asT'

Update Virtual Instance

Update the properties of a virtual instance.

POST /v1/orgs/self/virtualinstances/{virtualInstanceId}

Arguments

virtualInstanceIdrequiredstring(in path)
uuid of the virtual instance
new_sizeoptionalstring
requested virtual instance size
new_typeoptionalstring
monitoring_enabledoptionalboolean

Example Request

Example Response

curl --request POST \
    --url https://api.rs2.usw2.rockset.com/v1/orgs/self/virtualinstances/virtualInstanceId \
    -H 'Authorization: ApiKey aB35kDjg93J5nsf4GjwMeErAVd832F7ad4vhsW1S02kfZiab42sTsfW5Sxt25asT' \
  -H 'Content-Type: application/json' \
    -d '{
    "new_size": "LARGE"
  }'

Workspaces

Workspace Type

Workspaces are organizational containers for collections.

Attributes

created_atoptionalstring

ISO-8601 date of when workspace was created

created_byoptionalstring

email of user who created the workspace

nameoptionalstring

descriptive label and unique identifier

descriptionoptionalstring

longer explanation for the workspace

collection_countoptionalinteger

number of collections that are immediate children of workspace

Example Object

{
  "created_at": "2001-08-28T00:23:41Z",
  "created_by": "hello@rockset.com",
  "name": "event_logs",
  "description": "Datasets of system logs for the ops team.",
  "collection_count": 3
}

Create Workspace

Create a new workspace.

POST /v1/orgs/self/ws

Arguments

namerequiredstring
descriptive label and unique identifier
descriptionoptionalstring
longer explanation for the workspace

Example Request

Example Response

curl --request POST \
    --url https://api.rs2.usw2.rockset.com/v1/orgs/self/ws \
    -H 'Authorization: ApiKey aB35kDjg93J5nsf4GjwMeErAVd832F7ad4vhsW1S02kfZiab42sTsfW5Sxt25asT' \
  -H 'Content-Type: application/json' \
    -d '{
    "name": "event_logs",
    "description": "Datasets of system logs for the ops team."
  }'

Delete Workspace

Remove a workspace.

DELETE /v1/orgs/self/ws/{workspace}

Arguments

workspacerequiredstring(in path)
name of the workspace

Example Request

Example Response

curl --request DELETE \
    --url https://api.rs2.usw2.rockset.com/v1/orgs/self/ws/commons \
    -H 'Authorization: ApiKey aB35kDjg93J5nsf4GjwMeErAVd832F7ad4vhsW1S02kfZiab42sTsfW5Sxt25asT'

List Workspaces

List all workspaces in an organization.

GET /v1/orgs/self/ws

Arguments

fetch_across_regionsoptionalboolean

Example Request

Example Response

curl --request GET \
    --url https://api.rs2.usw2.rockset.com/v1/orgs/self/ws \
    -H 'Authorization: ApiKey aB35kDjg93J5nsf4GjwMeErAVd832F7ad4vhsW1S02kfZiab42sTsfW5Sxt25asT'

List Workspaces in Workspace

List workspaces under given workspace.

GET /v1/orgs/self/ws/{workspace}/ws

Arguments

workspacerequiredstring(in path)
name of the workspace

Example Request

Example Response

curl --request GET \
    --url https://api.rs2.usw2.rockset.com/v1/orgs/self/ws/commons/ws \
    -H 'Authorization: ApiKey aB35kDjg93J5nsf4GjwMeErAVd832F7ad4vhsW1S02kfZiab42sTsfW5Sxt25asT'

Retrieve Workspace

Get information about a single workspace.

GET /v1/orgs/self/ws/{workspace}

Arguments

workspacerequiredstring(in path)
name of the workspace

Example Request

Example Response

curl --request GET \
    --url https://api.rs2.usw2.rockset.com/v1/orgs/self/ws/commons \
    -H 'Authorization: ApiKey aB35kDjg93J5nsf4GjwMeErAVd832F7ad4vhsW1S02kfZiab42sTsfW5Sxt25asT'

Custom Roles (beta)

Create a Role

Create a role for your organization.

POST /v1/orgs/self/roles

Arguments

role_nameoptionalstring
Unique identifier for the role.
descriptionoptionalstring
Description for the role.
privilegesoptionalarray
List of privileges that will be associated with the role.
Show child attributes

Example Request

Example Response

curl --request POST \
    --url https://api.rs2.usw2.rockset.com/v1/orgs/self/roles \
    -H 'Authorization: ApiKey aB35kDjg93J5nsf4GjwMeErAVd832F7ad4vhsW1S02kfZiab42sTsfW5Sxt25asT' \
  -H 'Content-Type: application/json' \
    -d '{
    "role_name": "read_write",
    "description": "Role with read and write privileges to all collections.",
    "privileges": [
      {
        "action": "Create collection",
        "resource_name": "commons",
        "cluster": "*ALL*"
      }
    ]
  }'

Delete a Role

Delete a role for your organization.

DELETE /v1/orgs/self/roles/{roleName}

Arguments

roleNamerequiredstring(in path)

Example Request

Example Response

curl --request DELETE \
    --url https://api.rs2.usw2.rockset.com/v1/orgs/self/roles/roleName \
    -H 'Authorization: ApiKey aB35kDjg93J5nsf4GjwMeErAVd832F7ad4vhsW1S02kfZiab42sTsfW5Sxt25asT'

List Roles

List all roles for your organization.

GET /v1/orgs/self/roles

Arguments

No arguments.

Example Request

Example Response

curl --request GET \
    --url https://api.rs2.usw2.rockset.com/v1/orgs/self/roles \
    -H 'Authorization: ApiKey aB35kDjg93J5nsf4GjwMeErAVd832F7ad4vhsW1S02kfZiab42sTsfW5Sxt25asT'

Update a Role

Update a role for your organization.

POST /v1/orgs/self/roles/{roleName}

Arguments

roleNamerequiredstring(in path)
descriptionoptionalstring
Description for the role.
privilegesoptionalarray
List of privileges that will be associated with the role.
Show child attributes

Example Request

Example Response

curl --request POST \
    --url https://api.rs2.usw2.rockset.com/v1/orgs/self/roles/roleName \
    -H 'Authorization: ApiKey aB35kDjg93J5nsf4GjwMeErAVd832F7ad4vhsW1S02kfZiab42sTsfW5Sxt25asT' \
  -H 'Content-Type: application/json' \
    -d '{
    "description": "Role with read and write privileges to all collections.",
    "privileges": [
      {
        "action": "Create collection",
        "resource_name": "commons",
        "cluster": "*ALL*"
      }
    ]
  }'

Rockset API Reference

Authentication

#Queries

#QueryResponse Type

Attributes

query_idoptionalstring

collectionsoptionalarray

resultsoptionalarray

statsoptional

warningsoptionalarray

query_errorsoptionalarray

column_fieldsoptionalarray

results_total_doc_countoptionalinteger

paginationoptional

last_offsetoptionalstring

#Query

Arguments

sqlrequiredobject

#Validate Query

Arguments

sqlrequiredobject

#Documents

#Add Documents

Arguments

workspacerequiredstring(in path)

collectionrequiredstring(in path)

datarequiredarray

#Delete Documents

Arguments

workspacerequiredstring(in path)

collectionrequiredstring(in path)

datarequiredarray

#Patch Documents

Arguments

workspacerequiredstring(in path)

collectionrequiredstring(in path)

datarequiredarray

#API Keys

#Create API Key

Arguments

namerequiredstring

roleoptionalstring

#Delete API Key

Arguments

namerequiredstring(in path)

userrequiredstring(in path)

#List API Keys.

Arguments

userrequiredstring(in path)

#Retrieve API Key

Arguments

userrequiredstring(in path)

namerequiredstring(in path)

#Update an API key's state

Arguments

namerequiredstring(in path)

userrequiredstring(in path)

stateoptionalstring

#Aliases

#Create Alias

Arguments

workspacerequiredstring(in path)

namerequiredstring

descriptionoptionalstring

collectionsrequiredarray

#Delete Alias

Arguments

workspacerequiredstring(in path)

aliasrequiredstring(in path)

#List Aliases

Arguments

#List Aliases in Workspace

Arguments

workspacerequiredstring(in path)

#Retrieve Alias

Arguments

workspacerequiredstring(in path)

aliasrequiredstring(in path)

#Update Alias

Arguments

Queries

QueryResponse Type

Query

Validate Query

Documents

Add Documents

Delete Documents

Patch Documents

API Keys

Create API Key

Delete API Key

List API Keys.

Retrieve API Key

Update an API key's state

Aliases

Create Alias

Delete Alias

List Aliases

List Aliases in Workspace

Retrieve Alias

Update Alias

Collections

Collection Type

Create Collection

Delete Collection

List Collections

List Collections in Workspace

Retrieve Collection

Integrations

Integration Type

Create Integration