Rockset
Developer Tools
Terraform ProviderRockset CLINode.js ClientPython Client v1Python Client v0 (Deprecated)Java ClientGo ClientVS Code Extension
StatusSupportCommunity
GuidesSQL ReferenceAPI Reference
Queries
Cancel QueryExecute SQL QueryList QueriesRetrieve QueryRetrieve Query Results PageValidate Query
Documents
Add DocumentsDelete DocumentsPatch Documents
Aliases
Create AliasDelete AliasList AliasesList Aliases in WorkspaceRetrieve AliasUpdate Alias
API Keys
Create API KeyDelete API KeyList API KeysRetrieve API KeyUpdate API Key State
Collections
Create CollectionDelete CollectionGet Collection CommitList CollectionsList Collections in WorkspaceRetrieve CollectionUpdate Collection
Custom Roles
Create a RoleDelete a RoleList RolesRetrieve roleUpdate a Role
Integrations
Create IntegrationDelete IntegrationList IntegrationsRetrieve IntegrationUpdate Integration
Query Lambdas
Create Query LambdaCreate Query Lambda TagDelete Query LambdaDelete Query Lambda Tag VersionDelete Query Lambda VersionExecute Query Lambda By TagExecute Query Lambda By VersionList Query Lambda TagsList Query Lambda VersionsList Query LambdasList Query Lambdas in WorkspaceRetrieve Query Lambda TagRetrieve Query Lambda VersionUpdate Query Lambda
Shared Lambdas
Execute a Public Query Lambda
Sources
Create a sourceDelete Collection sourceList sources in collectionResume source ingestRetrieve sourceSuspend source ingestUpdate a collection source
Users
Create UserDelete UserList UsersRetrieve Current UserRetrieve Notification PreferencesRetrieve UserUpdate Notification PreferencesUpdate User
Views
Create ViewDelete ViewList ViewsList Views in WorkspaceRetrieve ViewUpdate View
Virtual Instances
Create Virtual InstanceDelete Virtual InstanceExecute SQL QueryGet Collection CommitGet Collection MountList Collection MountsList QueriesList Virtual InstancesMount CollectionsResume Virtual InstanceRetrieve Virtual InstanceSuspend Virtual InstanceUnmount CollectionUpdate Virtual Instance
Workspaces
Create WorkspaceDelete WorkspaceList WorkspacesRetrieve Workspace

Rockset API Reference

Introduction

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.

RegionBase URL
Oregon (us-west-2)https://api.usw2a1.rockset.com
N. Virginia (us-east-1)https://api.use1a1.rockset.com
Frankfurt (eu-central-1)https://api.euc1a1.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. You can find the OpenAPI version of these endpoints here.

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

Cancel Query

Attempts to cancel an actively-running query.

DELETE /v1/orgs/self/queries/{queryId}

Arguments

  • queryIdrequiredstring(in path)

Response

  • dataoptionalobject

    Show child attributes

Example Request
Example Response
curl --request DELETE \
    --url https://api.usw2a1.rockset.com/v1/orgs/self/queries/queryId \
    -H 'Authorization: ApiKey _insert_your_apikey_here_'

Execute SQL Query

Make a SQL query to Rockset.

POST /v1/orgs/self/queries

Arguments

  • sqlrequiredobject

    Main query request body.

    Show child attributes

  • asyncoptionalboolean

    If true, the query will run asynchronously for up to 30 minutes. The query request will immediately return with a query id that can be used to retrieve the query status and results. If false or not specified, the query will return with results once completed or timeout after 2 minutes. (To return results directly for shorter queries while still allowing a timeout of up to 30 minutes, set async_options.client_timeout_ms.)

  • async_optionsoptionalobject

    Options for configuring Asynchronous Query Mode.

    Show child attributes

  • debug_threshold_msoptionalinteger

    If query execution takes longer than this value, debug information will be logged. If the query text includes the DEBUG hint and this parameter is also provided, only this value will be used and the DEBUG hint will be ignored.

  • max_initial_resultsoptionalinteger

    This limits the maximum number of results in the initial response. A pagination cursor is returned if the number of results exceeds max_initial_results. If max_initial_results is not set, all results will be returned in the initial response up to 4 million. If max_initial_results is set, the value must be between 0 and 100,000. If the query is async and client_timeout_ms is exceeded, max_initial_results does not apply since none of the results will be returned with the initial response.

  • timeout_msoptionalinteger

    If a query exceeds the specified timeout, the query will automatically stop and return an error. The query timeout defaults to a maximum of 2 minutes. If async is true, the query timeout defaults to a maximum of 30 minutes.

Response

  • collectionsoptionalstring array

    List of collections referenced in the query.

  • column_fieldsoptionalobject array

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

    Show child attributes

  • last_offsetoptionalstring

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

  • paginationoptionalobject

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

    Show child attributes

  • query_errorsoptionalobject array

    Errors encountered while executing the query.

    Show child attributes

  • query_idoptionalstring

    Unique ID for this query.

  • query_lambda_pathoptionalstring

    The full path of the executed query lambda. Includes version information.

  • resultsoptionalobject array

    Results from the query.

  • results_total_doc_countoptionalinteger

    Number of results generated by the query.

  • statsoptionalobject

    Meta information about the query including execution latencies.

    Show child attributes

  • statusoptionalstring

    Status of query execution. Possible values: QUEUED, RUNNING, COMPLETED, ERROR. Possible values: QUEUED, RUNNING, COMPLETED, ERROR.

  • warningsoptionalstring array
Example Request
Example Response
curl --request POST \
    --url https://api.usw2a1.rockset.com/v1/orgs/self/queries \
    -H 'Authorization: ApiKey _insert_your_apikey_here_' \
  -H 'Content-Type: application/json' \
    -d '{
    "async": "true",
    "async_options": {
      "client_timeout_ms": "123"
    },
    "debug_threshold_ms": "123",
    "max_initial_results": "123",
    "sql": {
      "default_row_limit": "123",
      "parameters": [
        {
          "name": "_id",
          "value": "85beb391"
        }
      ],
      "query": "SELECT * FROM foo where _id = :_id"
    },
    "timeout_ms": "123"
  }'

List Queries

Lists actively queued and running queries.

GET /v1/orgs/self/queries

Arguments

    No arguments.

Response

  • dataoptionalobject array

    Show child attributes

Example Request
Example Response
curl --request GET \
    --url https://api.usw2a1.rockset.com/v1/orgs/self/queries \
    -H 'Authorization: ApiKey _insert_your_apikey_here_'

Retrieve Query

Returns information about a query.

GET /v1/orgs/self/queries/{queryId}

Arguments

  • queryIdrequiredstring(in path)

Response

  • dataoptionalobject

    Show child attributes

Example Request
Example Response
curl --request GET \
    --url https://api.usw2a1.rockset.com/v1/orgs/self/queries/queryId \
    -H 'Authorization: ApiKey _insert_your_apikey_here_'

Retrieve Query Results Page

Returns a page of query results.

GET /v1/orgs/self/queries/{queryId}/pages

Arguments

  • queryIdrequiredstring(in path)
  • cursoroptionalstring(query parameter)

    Cursor to current page. If unset, will default to the first page.

  • docsoptionalinteger(query parameter)

    Number of documents to fetch.

  • offsetoptionalinteger(query parameter)

    Offset from the cursor of the first document to be returned

Response

  • paginationoptionalobject

    Pagination metadata.

    Show child attributes

  • resultsoptionalobject array

    List of documents returned by the query.

  • results_total_doc_countoptionalinteger

    Total documents returned by the query.

Example Request
Example Response
curl --request GET \
    --url https://api.usw2a1.rockset.com/v1/orgs/self/queries/queryId/pages?cursor=deUIr8DsHgTw7c00&docs=100&offset=offset& \
    -H 'Authorization: ApiKey _insert_your_apikey_here_'

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

  • asyncoptionalboolean

    If true, the query will run asynchronously for up to 30 minutes. The query request will immediately return with a query id that can be used to retrieve the query status and results. If false or not specified, the query will return with results once completed or timeout after 2 minutes. (To return results directly for shorter queries while still allowing a timeout of up to 30 minutes, set async_options.client_timeout_ms.)

  • async_optionsoptionalobject

    Options for configuring Asynchronous Query Mode.

    Show child attributes

  • debug_threshold_msoptionalinteger

    If query execution takes longer than this value, debug information will be logged. If the query text includes the DEBUG hint and this parameter is also provided, only this value will be used and the DEBUG hint will be ignored.

  • max_initial_resultsoptionalinteger

    This limits the maximum number of results in the initial response. A pagination cursor is returned if the number of results exceeds max_initial_results. If max_initial_results is not set, all results will be returned in the initial response up to 4 million. If max_initial_results is set, the value must be between 0 and 100,000. If the query is async and client_timeout_ms is exceeded, max_initial_results does not apply since none of the results will be returned with the initial response.

  • timeout_msoptionalinteger

    If a query exceeds the specified timeout, the query will automatically stop and return an error. The query timeout defaults to a maximum of 2 minutes. If async is true, the query timeout defaults to a maximum of 30 minutes.

Response

  • collectionsrequiredstring array

    List of collections specified in query.

  • parametersrequiredstring array

    List of parameters specified in query.

Example Request
Example Response
curl --request POST \
    --url https://api.usw2a1.rockset.com/v1/orgs/self/queries/validations \
    -H 'Authorization: ApiKey _insert_your_apikey_here_' \
  -H 'Content-Type: application/json' \
    -d '{
    "async": "true",
    "async_options": {
      "client_timeout_ms": "123"
    },
    "debug_threshold_ms": "123",
    "max_initial_results": "123",
    "sql": {
      "default_row_limit": "123",
      "parameters": [
        {
          "name": "_id",
          "value": "85beb391"
        }
      ],
      "query": "SELECT * FROM foo where _id = :_id"
    },
    "timeout_ms": "123"
  }'

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.

  • datarequiredobject array

    Array of documents to be added to the collection.

Response

  • dataoptionalobject array

    Information about the added documents.

    Show child attributes

  • last_offsetoptionalstring

    A string representing the collection offset after completing the write.

Example Request
Example Response
curl --request POST \
    --url https://api.usw2a1.rockset.com/v1/orgs/self/ws/commons/collections/customers/docs \
    -H 'Authorization: ApiKey _insert_your_apikey_here_' \
  -H 'Content-Type: application/json' \
    -d '{
    "data": [
      {}
    ]
  }'

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.

  • datarequiredobject array

    Array of IDs of documents to be deleted.

    Show child attributes

Response

  • dataoptionalobject array

    Information about deleted documents.

    Show child attributes

  • last_offsetoptionalstring

    A string representing the collection offset after completing the deletes.

Example Request
Example Response
curl --request DELETE \
    --url https://api.usw2a1.rockset.com/v1/orgs/self/ws/commons/collections/customers/docs \
    -H 'Authorization: ApiKey _insert_your_apikey_here_' \
  -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.

  • datarequiredobject array

    List of patches to be applied.

    Show child attributes

Response

  • datarequiredobject array

    Show child attributes

  • last_offsetoptionalstring

    A string representing the collection offset after completing the patch.

Example Request
Example Response
curl --request PATCH \
    --url https://api.usw2a1.rockset.com/v1/orgs/self/ws/commons/collections/customers/docs \
    -H 'Authorization: ApiKey _insert_your_apikey_here_' \
  -H 'Content-Type: application/json' \
    -d '{
    "data": [
      {
        "_id": "ca2d6832-1bfd-f88f-0620-d2aa27a5d86c",
        "patch": [
          {
            "from": "foo",
            "op": "ADD",
            "path": "/foo/bar",
            "value": {}
          }
        ]
      }
    ]
  }'

Aliases

Create Alias

Create new alias in a workspace.

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

Arguments

  • workspacerequiredstring(in path)

    name of the workspace

  • collectionsrequiredstring array

    List of fully qualified collection names referenced by alias.

  • namerequiredstring

    Alias name.

  • descriptionoptionalstring

    Optional description.

Response

  • dataoptionalobject

    Alias that was created.

    Show child attributes

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

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

Response

  • dataoptionalobject

    Alias that was deleted.

    Show child attributes

Example Request
Example Response
curl --request DELETE \
    --url https://api.usw2a1.rockset.com/v1/orgs/self/ws/commons/aliases/alias \
    -H 'Authorization: ApiKey _insert_your_apikey_here_'

List Aliases

Retrieve all aliases in an organization

GET /v1/orgs/self/aliases

Arguments

    No arguments.

Response

  • dataoptionalobject array

    List of all aliases.

    Show child attributes

Example Request
Example Response
curl --request GET \
    --url https://api.usw2a1.rockset.com/v1/orgs/self/aliases \
    -H 'Authorization: ApiKey _insert_your_apikey_here_'

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

Response

  • dataoptionalobject array

    List of all aliases.

    Show child attributes

Example Request
Example Response
curl --request GET \
    --url https://api.usw2a1.rockset.com/v1/orgs/self/ws/commons/aliases \
    -H 'Authorization: ApiKey _insert_your_apikey_here_'

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

Response

  • dataoptionalobject

    Alias that was requested.

    Show child attributes

Example Request
Example Response
curl --request GET \
    --url https://api.usw2a1.rockset.com/v1/orgs/self/ws/commons/aliases/alias \
    -H 'Authorization: ApiKey _insert_your_apikey_here_'

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

  • collectionsrequiredstring array

    List of fully qualified collection names referenced by alias.

  • descriptionoptionalstring

    Optional description.

Response

  • dataoptionalobject

    Alias that was requested.

    Show child attributes

Example Request
Example Response
curl --request POST \
    --url https://api.usw2a1.rockset.com/v1/orgs/self/ws/commons/aliases/alias \
    -H 'Authorization: ApiKey _insert_your_apikey_here_' \
  -H 'Content-Type: application/json' \
    -d '{
    "collections": [
      "foo"
    ],
    "description": "version alias"
  }'

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.

  • created_byoptionalstring
  • roleoptionalstring

Response

  • dataoptionalobject

    The API key that was created.

    Show child attributes

Example Request
Example Response
curl --request POST \
    --url https://api.usw2a1.rockset.com/v1/orgs/self/users/self/apikeys \
    -H 'Authorization: ApiKey _insert_your_apikey_here_' \
  -H 'Content-Type: application/json' \
    -d '{
    "created_by": "foo",
    "name": "my-app",
    "role": "foo"
  }'

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.

Response

  • dataoptionalobject

    The API key that was deleted.

    Show child attributes

Example Request
Example Response
curl --request DELETE \
    --url https://api.usw2a1.rockset.com/v1/orgs/self/users/admin@me.com/apikeys/name \
    -H 'Authorization: ApiKey _insert_your_apikey_here_'

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.

Response

  • dataoptionalobject array

    List of API key objects.

    Show child attributes

Example Request
Example Response
curl --request GET \
    --url https://api.usw2a1.rockset.com/v1/orgs/self/users/admin@me.com/apikeys \
    -H 'Authorization: ApiKey _insert_your_apikey_here_'

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.

  • revealoptionalboolean(query parameter)

    Reveal full key.

Response

  • dataoptionalobject

    The requested API key object.

    Show child attributes

Example Request
Example Response
curl --request GET \
    --url https://api.usw2a1.rockset.com/v1/orgs/self/users/admin@me.com/apikeys/name?reveal=reveal& \
    -H 'Authorization: ApiKey _insert_your_apikey_here_'

Update API Key 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. Possible values: ACTIVE, SUSPENDED.

Response

  • dataoptionalobject

    The API key that was updated.

    Show child attributes

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

Collections

Create Collection

Create new collection in a workspace.

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

Arguments

  • workspacerequiredstring(in path)

    name of the workspace

  • descriptionoptionalstring

    Text describing the collection.

  • field_mapping_queryoptionalobject

    Ingest transformation query.

    Show child attributes

  • nameoptionalstring

    Unique identifier for collection, can contain alphanumeric or dash characters.

  • retention_secsoptionalinteger

    Number of seconds after which data is purged, based on event time.

  • source_download_soft_limit_bytesoptionalinteger

    Soft ingest limit for this collection.

  • sourcesoptionalobject array

    List of sources from which to ingest data.

    Show child attributes

  • storage_compression_typeoptionalstring

    RocksDB storage compression type. Possible values: LZ4, ZSTD.

  • clustering_keyoptionalobject array

    Deprecated. List of clustering fields. Use CLUSTER BY clause in field_mapping_query instead.

    Show child attributes

  • event_time_infooptionalobject

    Deprecated. Configuration for event data. Use an _event_time mapping in field_mapping_query instead.

    Show child attributes

Response

  • dataoptionalobject

    Collection that was created.

    Show child attributes

Example Request
Example Response
curl --request POST \
    --url https://api.usw2a1.rockset.com/v1/orgs/self/ws/commons/collections \
    -H 'Authorization: ApiKey _insert_your_apikey_here_' \
  -H 'Content-Type: application/json' \
    -d '{
    "description": "transactions from stores worldwide",
    "field_mapping_query": {
      "sql": "sql"
    },
    "name": "global-transactions",
    "retention_secs": 1000000,
    "source_download_soft_limit_bytes": "123",
    "sources": [
      {
        "integration_name": "aws-integration",
        "s3": {
          "bucket": "s3://customer-account-info",
          "pattern": "prefix/to/**/keys/*.format",
          "prefix": "prefix/to/keys",
          "region": "us-west-2",
          "settings": {
            "s3_scan_frequency": "5min"
          }
        }
      }
    ],
    "storage_compression_type": "LZ4"
  }'

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

Response

  • dataoptionalobject

    Collection that was deleted.

    Show child attributes

Example Request
Example Response
curl --request DELETE \
    --url https://api.usw2a1.rockset.com/v1/orgs/self/ws/commons/collections/customers \
    -H 'Authorization: ApiKey _insert_your_apikey_here_'

Get Collection Commit

Determines if the collection includes data at or after the specified fence(s) for close read-after-write semantics.

POST /v1/orgs/self/ws/{workspace}/collections/{collection}/offsets/commit

Arguments

  • workspacerequiredstring(in path)

    name of the workspace

  • collectionrequiredstring(in path)

    name of the collection

  • nameoptionalstring array

    a list of zero or more collection offset fences

Response

  • dataoptionalobject

    Show child attributes

  • offsetsoptionalobject

    Show child attributes

Example Request
Example Response
curl --request POST \
    --url https://api.usw2a1.rockset.com/v1/orgs/self/ws/commons/collections/customers/offsets/commit \
    -H 'Authorization: ApiKey _insert_your_apikey_here_' \
  -H 'Content-Type: application/json' \
    -d '{
    "name": [
      "foo"
    ]
  }'

List Collections

Retrieve all collections in an organization.

GET /v1/orgs/self/collections

Arguments

    No arguments.

Response

  • dataoptionalobject array

    List of all collections.

    Show child attributes

Example Request
Example Response
curl --request GET \
    --url https://api.usw2a1.rockset.com/v1/orgs/self/collections \
    -H 'Authorization: ApiKey _insert_your_apikey_here_'

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

Response

  • dataoptionalobject array

    List of all collections.

    Show child attributes

Example Request
Example Response
curl --request GET \
    --url https://api.usw2a1.rockset.com/v1/orgs/self/ws/commons/collections \
    -H 'Authorization: ApiKey _insert_your_apikey_here_'

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

Response

  • dataoptionalobject

    Collection that was requested.

    Show child attributes

Example Request
Example Response
curl --request GET \
    --url https://api.usw2a1.rockset.com/v1/orgs/self/ws/commons/collections/customers \
    -H 'Authorization: ApiKey _insert_your_apikey_here_'

Update Collection

Update details about a collection.

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

Arguments

  • workspacerequiredstring(in path)

    name of the workspace

  • collectionrequiredstring(in path)

    name of the collection

  • descriptionoptionalstring

    Updated text describing the collection.

  • field_mapping_queryoptionalobject

    Updated ingest transformation query. Note that updating the transformation will lead to a brief interruption in ingestion.

    Show child attributes

Response

  • dataoptionalobject

    Collection that was requested.

    Show child attributes

Example Request
Example Response
curl --request PUT \
    --url https://api.usw2a1.rockset.com/v1/orgs/self/ws/commons/collections/customers \
    -H 'Authorization: ApiKey _insert_your_apikey_here_' \
  -H 'Content-Type: application/json' \
    -d '{
    "description": "transactions from stores worldwide",
    "field_mapping_query": {
      "sql": "sql"
    }
  }'

Custom Roles

Create a Role

Create a role for your organization.

POST /v1/orgs/self/roles

Arguments

  • descriptionoptionalstring

    Description for the role.

  • privilegesoptionalobject array

    List of privileges that will be associated with the role.

    Show child attributes

  • role_nameoptionalstring

    Unique identifier for the role.

Response

  • dataoptionalobject

    Show child attributes

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

Delete a Role

Delete a role for your organization.

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

Arguments

  • roleNamerequiredstring(in path)

Response

  • dataoptionalobject

    Show child attributes

Example Request
Example Response
curl --request DELETE \
    --url https://api.usw2a1.rockset.com/v1/orgs/self/roles/roleName \
    -H 'Authorization: ApiKey _insert_your_apikey_here_'

List Roles

List all roles for your organization.

GET /v1/orgs/self/roles

Arguments

    No arguments.

Response

  • dataoptionalobject array

    List of all roles.

    Show child attributes

Example Request
Example Response
curl --request GET \
    --url https://api.usw2a1.rockset.com/v1/orgs/self/roles \
    -H 'Authorization: ApiKey _insert_your_apikey_here_'

Retrieve role

Retrieve a role by name for your organization.

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

Arguments

  • roleNamerequiredstring(in path)

Response

  • dataoptionalobject

    Show child attributes

Example Request
Example Response
curl --request GET \
    --url https://api.usw2a1.rockset.com/v1/orgs/self/roles/roleName \
    -H 'Authorization: ApiKey _insert_your_apikey_here_'

Update a Role

Update a role for your organization.

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

Arguments

  • roleNamerequiredstring(in path)
  • descriptionoptionalstring

    Description for the role.

  • privilegesoptionalobject array

    List of privileges that will be associated with the role.

    Show child attributes

Response

  • dataoptionalobject

    Show child attributes

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

Integrations

Create Integration

Create a new integration.

POST /v1/orgs/self/integrations

Arguments

  • namerequiredstring

    Descriptive label.

  • azure_blob_storageoptionalobject

    Azure Blob Storage details.

    Show child attributes

  • azure_event_hubsoptionalobject

    Azure Event Hubs details.

    Show child attributes

  • azure_service_busoptionalobject

    Azure Service Bus details.

    Show child attributes

  • descriptionoptionalstring

    Longer explanation for the integration.

  • dynamodboptionalobject

    Amazon DynamoDB details, must have one of aws_access_key or aws_role.

    Show child attributes

  • gcsoptionalobject

    GCS details.

    Show child attributes

  • kafkaoptionalobject

    Show child attributes

  • kinesisoptionalobject

    Amazon Kinesis details, must have one of aws_access_key or aws_role.

    Show child attributes

  • mongodboptionalobject

    MongoDb details.

    Show child attributes

  • s3optionalobject

    Amazon S3 details, must have one of aws_access_key or aws_role.

    Show child attributes

  • snowflakeoptionalobject

    Snowflake details.

    Show child attributes

Response

  • dataoptionalobject

    Integration object that was created.

    Show child attributes

Example Request
Example Response
curl --request POST \
    --url https://api.usw2a1.rockset.com/v1/orgs/self/integrations \
    -H 'Authorization: ApiKey _insert_your_apikey_here_' \
  -H 'Content-Type: application/json' \
    -d '{
    "azure_blob_storage": {
      "connection_string": "BlobEndpoint=https://<NamespaceName>.blob.core.windows.net;\nSharedAccessSignature=<KeyValue>"
    },
    "azure_event_hubs": {
      "connection_string": "Endpoint=sb://<NamespaceName>.servicebus.windows.net/;SharedAccessKeyName=<KeyName>;SharedAccessKey=<KeyValue>"
    },
    "azure_service_bus": {
      "connection_string": "Endpoint=sb://<NamespaceName>.servicebus.windows.net/;SharedAccessKeyName=<KeyName>;SharedAccessKey=<KeyValue>"
    },
    "description": "AWS account with event data for the data science team.",
    "dynamodb": {
      "aws_access_key": {
        "aws_access_key_id": "AKIAIOSFODNN7EXAMPLE",
        "aws_secret_access_key": "wJal...."
      },
      "aws_role": {
        "aws_external_id": "external id of aws",
        "aws_role_arn": "arn:aws:iam::2378964092:role/rockset-role"
      },
      "s3_export_bucket_name": "foo"
    },
    "gcs": {
      "gcp_service_account": {
        "service_account_key_file_json": "foo"
      }
    },
    "kafka": {
      "aws_role": {
        "aws_external_id": "external id of aws",
        "aws_role_arn": "arn:aws:iam::2378964092:role/rockset-role"
      },
      "bootstrap_servers": "localhost:9092",
      "connection_string": "foo",
      "kafka_data_format": "JSON",
      "kafka_topic_names": [
        "foo"
      ],
      "schema_registry_config": {
        "key": "foo",
        "secret": "foo",
        "url": "foo"
      },
      "security_config": {
        "api_key": "foo",
        "secret": "foo"
      },
      "use_v3": "true"
    },
    "kinesis": {
      "aws_access_key": {
        "aws_access_key_id": "AKIAIOSFODNN7EXAMPLE",
        "aws_secret_access_key": "wJal...."
      },
      "aws_role": {
        "aws_external_id": "external id of aws",
        "aws_role_arn": "arn:aws:iam::2378964092:role/rockset-role"
      }
    },
    "mongodb": {
      "connection_uri": "mongodb+srv://<username>:<password>@server.example.com/",
      "tls": {
        "ca_cert": "-----BEGIN CERTIFICATE-----\n....\n-----END CERTIFICATE-----",
        "client_cert": "-----BEGIN CERTIFICATE-----\n....\n-----END CERTIFICATE-----",
        "client_key": "-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----"
      }
    },
    "name": "event-logs",
    "s3": {
      "aws_access_key": {
        "aws_access_key_id": "AKIAIOSFODNN7EXAMPLE",
        "aws_secret_access_key": "wJal...."
      },
      "aws_role": {
        "aws_external_id": "external id of aws",
        "aws_role_arn": "arn:aws:iam::2378964092:role/rockset-role"
      }
    },
    "snowflake": {
      "aws_access_key": {
        "aws_access_key_id": "AKIAIOSFODNN7EXAMPLE",
        "aws_secret_access_key": "wJal...."
      },
      "aws_role": {
        "aws_external_id": "external id of aws",
        "aws_role_arn": "arn:aws:iam::2378964092:role/rockset-role"
      },
      "default_warehouse": "foo",
      "password": "foo",
      "s3_export_path": "s3://bucket/prefix",
      "snowflake_url": "acme-marketing-test-account.snowflakecomputing.com",
      "user_role": "foo",
      "username": "foo"
    }
  }'

Delete Integration

Remove an integration.

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

Arguments

  • integrationrequiredstring(in path)

    name of the integration

Response

  • dataoptionalobject

    Integration object that was deleted.

    Show child attributes

Example Request
Example Response
curl --request DELETE \
    --url https://api.usw2a1.rockset.com/v1/orgs/self/integrations/my-aws-creds \
    -H 'Authorization: ApiKey _insert_your_apikey_here_'

List Integrations

List all integrations in an organization.

GET /v1/orgs/self/integrations

Arguments

    No arguments.

Response

  • dataoptionalobject array

    List of integration objects.

    Show child attributes

Example Request
Example Response
curl --request GET \
    --url https://api.usw2a1.rockset.com/v1/orgs/self/integrations \
    -H 'Authorization: ApiKey _insert_your_apikey_here_'

Retrieve Integration

Retrieve information about a single integration.

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

Arguments

  • integrationrequiredstring(in path)

    name of the integration

Response

  • dataoptionalobject

    Integration object.

    Show child attributes

Example Request
Example Response
curl --request GET \
    --url https://api.usw2a1.rockset.com/v1/orgs/self/integrations/my-aws-creds \
    -H 'Authorization: ApiKey _insert_your_apikey_here_'

Update Integration

Update an existing integration.

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

Arguments

  • integrationrequiredstring(in path)
  • azure_blob_storageoptionalobject

    Azure Blob Storage details.

    Show child attributes

  • azure_event_hubsoptionalobject

    Azure Event Hubs details.

    Show child attributes

  • azure_service_busoptionalobject

    Azure Service Bus details.

    Show child attributes

  • descriptionoptionalstring

    Longer explanation for the integration.

  • dynamodboptionalobject

    Amazon DynamoDB details, must have one of aws_access_key or aws_role.

    Show child attributes

  • gcsoptionalobject

    GCS details.

    Show child attributes

  • kafkaoptionalobject

    Show child attributes

  • kinesisoptionalobject

    Amazon Kinesis details, must have one of aws_access_key or aws_role.

    Show child attributes

  • mongodboptionalobject

    MongoDb details.

    Show child attributes

  • s3optionalobject

    Amazon S3 details, must have one of aws_access_key or aws_role.

    Show child attributes

  • snowflakeoptionalobject

    Snowflake details.

    Show child attributes

Response

  • dataoptionalobject

    Updated integration object.

    Show child attributes

Example Request
Example Response
curl --request PUT \
    --url https://api.usw2a1.rockset.com/v1/orgs/self/integrations/my-aws-creds \
    -H 'Authorization: ApiKey _insert_your_apikey_here_' \
  -H 'Content-Type: application/json' \
    -d '{
    "azure_blob_storage": {
      "connection_string": "BlobEndpoint=https://<NamespaceName>.blob.core.windows.net;\nSharedAccessSignature=<KeyValue>"
    },
    "azure_event_hubs": {
      "connection_string": "Endpoint=sb://<NamespaceName>.servicebus.windows.net/;SharedAccessKeyName=<KeyName>;SharedAccessKey=<KeyValue>"
    },
    "azure_service_bus": {
      "connection_string": "Endpoint=sb://<NamespaceName>.servicebus.windows.net/;SharedAccessKeyName=<KeyName>;SharedAccessKey=<KeyValue>"
    },
    "description": "AWS account with event data for the data science team.",
    "dynamodb": {
      "aws_access_key": {
        "aws_access_key_id": "AKIAIOSFODNN7EXAMPLE",
        "aws_secret_access_key": "wJal...."
      },
      "aws_role": {
        "aws_external_id": "external id of aws",
        "aws_role_arn": "arn:aws:iam::2378964092:role/rockset-role"
      },
      "s3_export_bucket_name": "foo"
    },
    "gcs": {
      "gcp_service_account": {
        "service_account_key_file_json": "foo"
      }
    },
    "kafka": {
      "aws_role": {
        "aws_external_id": "external id of aws",
        "aws_role_arn": "arn:aws:iam::2378964092:role/rockset-role"
      },
      "bootstrap_servers": "localhost:9092",
      "connection_string": "foo",
      "kafka_data_format": "JSON",
      "kafka_topic_names": [
        "foo"
      ],
      "schema_registry_config": {
        "key": "foo",
        "secret": "foo",
        "url": "foo"
      },
      "security_config": {
        "api_key": "foo",
        "secret": "foo"
      },
      "use_v3": "true"
    },
    "kinesis": {
      "aws_access_key": {
        "aws_access_key_id": "AKIAIOSFODNN7EXAMPLE",
        "aws_secret_access_key": "wJal...."
      },
      "aws_role": {
        "aws_external_id": "external id of aws",
        "aws_role_arn": "arn:aws:iam::2378964092:role/rockset-role"
      }
    },
    "mongodb": {
      "connection_uri": "mongodb+srv://<username>:<password>@server.example.com/",
      "tls": {
        "ca_cert": "-----BEGIN CERTIFICATE-----\n....\n-----END CERTIFICATE-----",
        "client_cert": "-----BEGIN CERTIFICATE-----\n....\n-----END CERTIFICATE-----",
        "client_key": "-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----"
      }
    },
    "s3": {
      "aws_access_key": {
        "aws_access_key_id": "AKIAIOSFODNN7EXAMPLE",
        "aws_secret_access_key": "wJal...."
      },
      "aws_role": {
        "aws_external_id": "external id of aws",
        "aws_role_arn": "arn:aws:iam::2378964092:role/rockset-role"
      }
    },
    "snowflake": {
      "aws_access_key": {
        "aws_access_key_id": "AKIAIOSFODNN7EXAMPLE",
        "aws_secret_access_key": "wJal...."
      },
      "aws_role": {
        "aws_external_id": "external id of aws",
        "aws_role_arn": "arn:aws:iam::2378964092:role/rockset-role"
      },
      "default_warehouse": "foo",
      "password": "foo",
      "s3_export_path": "s3://bucket/prefix",
      "snowflake_url": "acme-marketing-test-account.snowflakecomputing.com",
      "user_role": "foo",
      "username": "foo"
    }
  }'

Query Lambdas

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.

  • sqlrequiredobject

    Query Lambda SQL query.

    Show child attributes

  • descriptionoptionalstring

    Optional description.

  • is_publicoptionalboolean

Response

  • dataoptionalobject

    Query Lambda version details.

    Show child attributes

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

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.

Response

  • dataoptionalobject

    Updated Query Lambda tag.

    Show child attributes

Example Request
Example Response
curl --request POST \
    --url https://api.usw2a1.rockset.com/v1/orgs/self/ws/commons/lambdas/queryLambda/tags \
    -H 'Authorization: ApiKey _insert_your_apikey_here_' \
  -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

Response

  • dataoptionalobject

    Query Lambda details.

    Show child attributes

Example Request
Example Response
curl --request DELETE \
    --url https://api.usw2a1.rockset.com/v1/orgs/self/ws/commons/lambdas/queryLambda \
    -H 'Authorization: ApiKey _insert_your_apikey_here_'

Delete Query Lambda Tag Version

Delete a tag for a specific Query Lambda

DELETE /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

Response

  • dataoptionalobject

    Updated Query Lambda tag.

    Show child attributes

Example Request
Example Response
curl --request DELETE \
    --url https://api.usw2a1.rockset.com/v1/orgs/self/ws/commons/lambdas/queryLambda/tags/tag \
    -H 'Authorization: ApiKey _insert_your_apikey_here_'

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

Response

  • dataoptionalobject

    Query Lambda version details.

    Show child attributes

Example Request
Example Response
curl --request DELETE \
    --url https://api.usw2a1.rockset.com/v1/orgs/self/ws/commons/lambdas/queryLambda/version/version \
    -H 'Authorization: ApiKey _insert_your_apikey_here_'

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

  • asyncoptionalboolean

    If true, the query will run asynchronously for up to 30 minutes. The query request will immediately return with a query id that can be used to retrieve the query status and results. If false or not specified, the query will return with results once completed or timeout after 2 minutes. (To return results directly for shorter queries while still allowing a timeout of up to 30 minutes, set async_options.client_timeout_ms.)

  • async_optionsoptionalobject

    Options for configuring Asynchronous Query Mode.

    Show child attributes

  • debug_threshold_msoptionalinteger

    If query execution takes longer than this value, debug information will be logged. If the query text includes the DEBUG hint and this parameter is also provided, only this value will be used and the DEBUG hint will be ignored.

  • default_row_limitoptionalinteger

    Row limit to use if no limit specified in the SQL query text.

  • max_initial_resultsoptionalinteger

    This limits the maximum number of results in the initial response. A pagination cursor is returned if the number of results exceeds max_initial_results. If max_initial_results is not set, all results will be returned in the initial response up to 4 million. If max_initial_results is set, the value must be between 0 and 100,000. If the query is async and client_timeout_ms is exceeded, max_initial_results does not apply since none of the results will be returned with the initial response.

  • paginateoptionalboolean

    Flag to paginate and store the results of this query for later / sequential retrieval.

  • parametersoptionalobject array

    List of named parameters.

    Show child attributes

  • timeout_msoptionalinteger

    If a query exceeds the specified timeout, the query will automatically stop and return an error. The query timeout defaults to a maximum of 2 minutes. If async is true, the query timeout defaults to a maximum of 30 minutes.

  • virtual_instance_idoptionalstring

    Virtual instance on which to run the query.

  • initial_paginate_response_doc_countoptionalinteger

    DEPRECATED Use max_initial_results instead. Number of documents to return in addition to paginating for this query call. Only relevant if paginate flag is also set.

Response

  • collectionsoptionalstring array

    List of collections referenced in the query.

  • column_fieldsoptionalobject array

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

    Show child attributes

  • last_offsetoptionalstring

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

  • paginationoptionalobject

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

    Show child attributes

  • query_errorsoptionalobject array

    Errors encountered while executing the query.

    Show child attributes

  • query_idoptionalstring

    Unique ID for this query.

  • query_lambda_pathoptionalstring

    The full path of the executed query lambda. Includes version information.

  • resultsoptionalobject array

    Results from the query.

  • results_total_doc_countoptionalinteger

    Number of results generated by the query.

  • statsoptionalobject

    Meta information about the query including execution latencies.

    Show child attributes

  • statusoptionalstring

    Status of query execution. Possible values: QUEUED, RUNNING, COMPLETED, ERROR. Possible values: QUEUED, RUNNING, COMPLETED, ERROR.

  • warningsoptionalstring array
Example Request
Example Response
curl --request POST \
    --url https://api.usw2a1.rockset.com/v1/orgs/self/ws/commons/lambdas/queryLambda/tags/tag \
    -H 'Authorization: ApiKey _insert_your_apikey_here_' \
  -H 'Content-Type: application/json' \
    -d '{
    "async": "true",
    "async_options": {
      "client_timeout_ms": "123"
    },
    "debug_threshold_ms": "123",
    "default_row_limit": "123",
    "max_initial_results": "123",
    "paginate": "true",
    "parameters": [
      {
        "name": "_id",
        "value": "85beb391"
      }
    ],
    "timeout_ms": "123",
    "virtual_instance_id": "foo"
  }'

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

  • asyncoptionalboolean

    If true, the query will run asynchronously for up to 30 minutes. The query request will immediately return with a query id that can be used to retrieve the query status and results. If false or not specified, the query will return with results once completed or timeout after 2 minutes. (To return results directly for shorter queries while still allowing a timeout of up to 30 minutes, set async_options.client_timeout_ms.)

  • async_optionsoptionalobject

    Options for configuring Asynchronous Query Mode.

    Show child attributes

  • debug_threshold_msoptionalinteger

    If query execution takes longer than this value, debug information will be logged. If the query text includes the DEBUG hint and this parameter is also provided, only this value will be used and the DEBUG hint will be ignored.

  • default_row_limitoptionalinteger

    Row limit to use if no limit specified in the SQL query text.

  • max_initial_resultsoptionalinteger

    This limits the maximum number of results in the initial response. A pagination cursor is returned if the number of results exceeds max_initial_results. If max_initial_results is not set, all results will be returned in the initial response up to 4 million. If max_initial_results is set, the value must be between 0 and 100,000. If the query is async and client_timeout_ms is exceeded, max_initial_results does not apply since none of the results will be returned with the initial response.

  • paginateoptionalboolean

    Flag to paginate and store the results of this query for later / sequential retrieval.

  • parametersoptionalobject array

    List of named parameters.

    Show child attributes

  • timeout_msoptionalinteger

    If a query exceeds the specified timeout, the query will automatically stop and return an error. The query timeout defaults to a maximum of 2 minutes. If async is true, the query timeout defaults to a maximum of 30 minutes.

  • virtual_instance_idoptionalstring

    Virtual instance on which to run the query.

  • initial_paginate_response_doc_countoptionalinteger

    DEPRECATED Use max_initial_results instead. Number of documents to return in addition to paginating for this query call. Only relevant if paginate flag is also set.

Response

  • collectionsoptionalstring array

    List of collections referenced in the query.

  • column_fieldsoptionalobject array

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

    Show child attributes

  • last_offsetoptionalstring

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

  • paginationoptionalobject

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

    Show child attributes

  • query_errorsoptionalobject array

    Errors encountered while executing the query.

    Show child attributes

  • query_idoptionalstring

    Unique ID for this query.

  • query_lambda_pathoptionalstring

    The full path of the executed query lambda. Includes version information.

  • resultsoptionalobject array

    Results from the query.

  • results_total_doc_countoptionalinteger

    Number of results generated by the query.

  • statsoptionalobject

    Meta information about the query including execution latencies.

    Show child attributes

  • statusoptionalstring

    Status of query execution. Possible values: QUEUED, RUNNING, COMPLETED, ERROR. Possible values: QUEUED, RUNNING, COMPLETED, ERROR.

  • warningsoptionalstring array
Example Request
Example Response
curl --request POST \
    --url https://api.usw2a1.rockset.com/v1/orgs/self/ws/commons/lambdas/queryLambda/versions/version \
    -H 'Authorization: ApiKey _insert_your_apikey_here_' \
  -H 'Content-Type: application/json' \
    -d '{
    "async": "true",
    "async_options": {
      "client_timeout_ms": "123"
    },
    "debug_threshold_ms": "123",
    "default_row_limit": "123",
    "max_initial_results": "123",
    "paginate": "true",
    "parameters": [
      {
        "name": "_id",
        "value": "85beb391"
      }
    ],
    "timeout_ms": "123",
    "virtual_instance_id": "foo"
  }'

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

Response

  • dataoptionalobject array

    List of all tags associated with a Query Lambda.

    Show child attributes

Example Request
Example Response
curl --request GET \
    --url https://api.usw2a1.rockset.com/v1/orgs/self/ws/commons/lambdas/queryLambda/tags \
    -H 'Authorization: ApiKey _insert_your_apikey_here_'

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

Response

  • dataoptionalobject array

    List of all versions for a particular Query Lambda.

    Show child attributes

Example Request
Example Response
curl --request GET \
    --url https://api.usw2a1.rockset.com/v1/orgs/self/ws/commons/lambdas/queryLambda/versions \
    -H 'Authorization: ApiKey _insert_your_apikey_here_'

List Query Lambdas

List all Query Lambdas in an organization.

GET /v1/orgs/self/lambdas

Arguments

    No arguments.

Response

  • dataoptionalobject array

    List of all Query Lambdas.

    Show child attributes

Example Request
Example Response
curl --request GET \
    --url https://api.usw2a1.rockset.com/v1/orgs/self/lambdas \
    -H 'Authorization: ApiKey _insert_your_apikey_here_'

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

Response

  • dataoptionalobject array

    List of all Query Lambdas.

    Show child attributes

Example Request
Example Response
curl --request GET \
    --url https://api.usw2a1.rockset.com/v1/orgs/self/ws/commons/lambdas \
    -H 'Authorization: ApiKey _insert_your_apikey_here_'

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

Response

  • dataoptionalobject

    Updated Query Lambda tag.

    Show child attributes

Example Request
Example Response
curl --request GET \
    --url https://api.usw2a1.rockset.com/v1/orgs/self/ws/commons/lambdas/queryLambda/tags/tag \
    -H 'Authorization: ApiKey _insert_your_apikey_here_'

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

Response

  • dataoptionalobject

    Query Lambda version details.

    Show child attributes

Example Request
Example Response
curl --request GET \
    --url https://api.usw2a1.rockset.com/v1/orgs/self/ws/commons/lambdas/queryLambda/versions/version \
    -H 'Authorization: ApiKey _insert_your_apikey_here_'

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

  • createoptionalboolean(query parameter)

    Create a new Query Lambda if one does not exist already.

  • descriptionoptionalstring

    Optional description.

  • is_publicoptionalboolean
  • sqloptionalobject

    Query Lambda SQL query.

    Show child attributes

Response

  • dataoptionalobject

    Query Lambda version details.

    Show child attributes

Example Request
Example Response
curl --request POST \
    --url https://api.usw2a1.rockset.com/v1/orgs/self/ws/commons/lambdas/queryLambda/versions?create=create& \
    -H 'Authorization: ApiKey _insert_your_apikey_here_' \
  -H 'Content-Type: application/json' \
    -d '{
    "description": "production version foo",
    "is_public": "true",
    "sql": {
      "default_parameters": [
        {
          "name": "_id",
          "value": "85beb391"
        }
      ],
      "query": "SELECT '\''Foo'\''"
    }
  }'

Shared Lambdas

Execute a Public Query Lambda

Execute a public query lambda (full version).

POST /v1/public/shared_lambdas/{public_access_id}

Arguments

  • public_access_idrequiredstring(in path)

    public access ID of the query lambda

  • default_row_limitoptionalinteger

    Row limit to use if no limit specified in the SQL query text.

  • parametersoptionalobject array

    List of named parameters.

    Show child attributes

Response

  • collectionsoptionalstring array

    List of collections referenced in the query.

  • column_fieldsoptionalobject array

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

    Show child attributes

  • last_offsetoptionalstring

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

  • paginationoptionalobject

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

    Show child attributes

  • query_errorsoptionalobject array

    Errors encountered while executing the query.

    Show child attributes

  • query_idoptionalstring

    Unique ID for this query.

  • query_lambda_pathoptionalstring

    The full path of the executed query lambda. Includes version information.

  • resultsoptionalobject array

    Results from the query.

  • results_total_doc_countoptionalinteger

    Number of results generated by the query.

  • statsoptionalobject

    Meta information about the query including execution latencies.

    Show child attributes

  • statusoptionalstring

    Status of query execution. Possible values: QUEUED, RUNNING, COMPLETED, ERROR. Possible values: QUEUED, RUNNING, COMPLETED, ERROR.

  • warningsoptionalstring array
Example Request
Example Response
curl --request POST \
    --url https://api.usw2a1.rockset.com/v1/public/shared_lambdas/public_access_id \
    -H 'Authorization: ApiKey _insert_your_apikey_here_' \
  -H 'Content-Type: application/json' \
    -d '{
    "default_row_limit": "123",
    "parameters": [
      {
        "name": "_id",
        "value": "85beb391"
      }
    ]
  }'

Sources

Create a source

Create new source in a collection.

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

Arguments

  • workspacerequiredstring(in path)

    name of the workspace

  • collectionrequiredstring(in path)

    name of the collection

  • azure_blob_storageoptionalobject

    Configuration for ingestion from Azure Blob Storage.

    Show child attributes

  • azure_event_hubsoptionalobject

    Configuration for ingestion from Azure Event Hubs.

    Show child attributes

  • azure_service_busoptionalobject

    Show child attributes

  • dynamodboptionalobject

    Configuration for ingestion from a dynamodb table.

    Show child attributes

  • format_paramsoptionalobject

    Format parameters for data from this source.

    Show child attributes

  • gcsoptionalobject

    Configuration for ingestion from GCS.

    Show child attributes

  • ingest_transformationoptionalobject

    Ingest transformation for a source.

    Show child attributes

  • integration_nameoptionalstring

    Name of integration to use.

  • kafkaoptionalobject

    Kafka collection identifier.

    Show child attributes

  • kinesisoptionalobject

    Configuration for ingestion from kinesis stream.

    Show child attributes

  • mongodboptionalobject

    MongoDB collection details.

    Show child attributes

  • s3optionalobject

    Configuration for ingestion from S3.

    Show child attributes

  • snowflakeoptionalobject

    Configuration for ingestion from Snowflake.

    Show child attributes

  • systemoptionalobject

    Show child attributes

Response

  • dataoptionalobject

    source config for source

    Show child attributes

Example Request
Example Response
curl --request POST \
    --url https://api.usw2a1.rockset.com/v1/orgs/self/ws/commons/collections/customers/sources \
    -H 'Authorization: ApiKey _insert_your_apikey_here_' \
  -H 'Content-Type: application/json' \
    -d '{
    "azure_blob_storage": {
      "container": "server-logs",
      "pattern": "prefix/to/**/keys/*.format",
      "prefix": "prefix/to/blobs",
      "settings": {
        "azblob_scan_frequency": "5min"
      }
    },
    "azure_event_hubs": {
      "hub_id": "event-hub-1",
      "offset_reset_policy": "EARLIEST"
    },
    "azure_service_bus": {
      "subscription": "rockset-subscription",
      "topic": "rockset-topic"
    },
    "dynamodb": {
      "aws_region": "us-east-2",
      "rcu": 1000,
      "table_name": "dynamodb_table_name",
      "use_scan_api": "true"
    },
    "format_params": {
      "avro": {},
      "csv": {
        "columnNames": [
          "foo"
        ],
        "columnTypes": [
          "foo"
        ],
        "encoding": "UTF-8",
        "escapeChar": "\\",
        "firstLineAsColumnNames": true,
        "quoteChar": "\"",
        "separator": ","
      },
      "json": true,
      "mssql_dms": "true",
      "mysql_dms": "true",
      "oracle_dms": "true",
      "postgres_dms": "true",
      "xml": {
        "attribute_prefix": "_attr",
        "doc_tag": "row",
        "encoding": "UTF-8",
        "root_tag": "root",
        "value_tag": "value"
      }
    },
    "gcs": {
      "bucket": "server-logs",
      "pattern": "prefix/to/**/keys/*.format",
      "prefix": "prefix/to/keys",
      "settings": {
        "gcs_scan_frequency": "5min"
      }
    },
    "ingest_transformation": {
      "sql": "sql"
    },
    "integration_name": "aws-integration",
    "kafka": {
      "consumer_group_id": "org-collection",
      "kafka_topic_name": "example-topic",
      "offset_reset_policy": "EARLIEST",
      "use_v3": "true"
    },
    "kinesis": {
      "aws_region": "us-east-2",
      "dms_primary_key": [
        "foo"
      ],
      "offset_reset_policy": "EARLIEST",
      "stream_name": "click_stream"
    },
    "mongodb": {
      "collection_name": "my_collection",
      "database_name": "my_database",
      "retrieve_full_document": "true"
    },
    "s3": {
      "bucket": "s3://customer-account-info",
      "pattern": "prefix/to/**/keys/*.format",
      "prefix": "prefix/to/keys",
      "region": "us-west-2",
      "settings": {
        "s3_scan_frequency": "5min"
      }
    },
    "snowflake": {
      "database": "NASDAQ",
      "schema": "PUBLIC",
      "table_name": "COMPANIES",
      "warehouse": "COMPUTE_XL"
    },
    "system": {
      "type": "QUERY_LOGS"
    }
  }'

Delete Collection source

Delete a collection source

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

Arguments

  • workspacerequiredstring(in path)

    name of the workspace

  • collectionrequiredstring(in path)

    name of the collection

  • sourcerequiredstring(in path)

    id of source

Response

  • dataoptionalobject

    source that was deleted

    Show child attributes

Example Request
Example Response
curl --request DELETE \
    --url https://api.usw2a1.rockset.com/v1/orgs/self/ws/commons/collections/customers/sources/source \
    -H 'Authorization: ApiKey _insert_your_apikey_here_'

List sources in collection

Retrieve all sources in a collection.

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

Arguments

  • workspacerequiredstring(in path)

    name of the workspace

  • collectionrequiredstring(in path)

    name of the collection

Response

  • dataoptionalobject array

    List of all sources in a collection

    Show child attributes

Example Request
Example Response
curl --request GET \
    --url https://api.usw2a1.rockset.com/v1/orgs/self/ws/commons/collections/customers/sources \
    -H 'Authorization: ApiKey _insert_your_apikey_here_'

Resume source ingest

Resume source ingest

POST /v1/orgs/self/ws/{workspace}/collections/{collection}/sources/{source}/resume

Arguments

  • workspacerequiredstring(in path)

    name of the workspace

  • collectionrequiredstring(in path)

    name of the collection

  • sourcerequiredstring(in path)

    id of source

Response

  • dataoptionalobject

    source config for source

    Show child attributes

Example Request
Example Response
curl --request POST \
    --url https://api.usw2a1.rockset.com/v1/orgs/self/ws/commons/collections/customers/sources/source/resume \
    -H 'Authorization: ApiKey _insert_your_apikey_here_'

Retrieve source

Get details about a collection source.

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

Arguments

  • workspacerequiredstring(in path)

    name of the workspace

  • collectionrequiredstring(in path)

    name of the collection

  • sourcerequiredstring(in path)

    id of source

Response

  • dataoptionalobject

    source config for source

    Show child attributes

Example Request
Example Response
curl --request GET \
    --url https://api.usw2a1.rockset.com/v1/orgs/self/ws/commons/collections/customers/sources/source \
    -H 'Authorization: ApiKey _insert_your_apikey_here_'

Suspend source ingest

Suspend source ingest

POST /v1/orgs/self/ws/{workspace}/collections/{collection}/sources/{source}/suspend

Arguments

  • workspacerequiredstring(in path)

    name of the workspace

  • collectionrequiredstring(in path)

    name of the collection

  • sourcerequiredstring(in path)

    id of source

  • resume_after_durationoptionalstring

    duration to suspend source; 1h is the default

Response

  • dataoptionalobject

    source config for source

    Show child attributes

Example Request
Example Response
curl --request POST \
    --url https://api.usw2a1.rockset.com/v1/orgs/self/ws/commons/collections/customers/sources/source/suspend \
    -H 'Authorization: ApiKey _insert_your_apikey_here_' \
  -H 'Content-Type: application/json' \
    -d '{
    "resume_after_duration": "30min"
  }'

Update a collection source

Update details about a collection source.

PUT /v1/orgs/self/ws/{workspace}/collections/{collection}/sources/{source}

Arguments

  • workspacerequiredstring(in path)

    name of the workspace

  • collectionrequiredstring(in path)

    name of the collection

  • sourcerequiredstring(in path)

    id of source

  • azure_blob_storageoptionalobject

    Configuration for ingestion from Azure Blob Storage.

    Show child attributes

  • dynamodboptionalobject

    Configuration for ingestion from a DynamoDb table.

    Show child attributes

  • gcsoptionalobject

    Configuration for ingestion from GCS.

    Show child attributes

  • s3optionalobject

    Configuration for ingestion from S3.

    Show child attributes

Response

  • dataoptionalobject

    source config for source

    Show child attributes

Example Request
Example Response
curl --request PUT \
    --url https://api.usw2a1.rockset.com/v1/orgs/self/ws/commons/collections/customers/sources/source \
    -H 'Authorization: ApiKey _insert_your_apikey_here_' \
  -H 'Content-Type: application/json' \
    -d '{
    "azure_blob_storage": {
      "settings": {
        "azblob_scan_frequency": "5min"
      }
    },
    "dynamodb": {
      "aws_region": "us-east-2",
      "rcu": 1000,
      "table_name": "dynamodb_table_name",
      "use_scan_api": "true"
    },
    "gcs": {
      "settings": {
        "gcs_scan_frequency": "5min"
      }
    },
    "s3": {
      "settings": {
        "s3_scan_frequency": "5min"
      }
    }
  }'

Users

Create User

Create a new user for an organization.

POST /v1/orgs/self/users

Arguments

  • emailrequiredstring

    User email, must be unique.

  • rolesrequiredstring array

    List of roles for a given user.

  • first_nameoptionalstring

    User first name.

  • last_nameoptionalstring

    User last name.

Response

  • dataoptionalobject

    User that was created.

    Show child attributes

Example Request
Example Response
curl --request POST \
    --url https://api.usw2a1.rockset.com/v1/orgs/self/users \
    -H 'Authorization: ApiKey _insert_your_apikey_here_' \
  -H 'Content-Type: application/json' \
    -d '{
    "email": "hello@rockset.com",
    "first_name": "John",
    "last_name": "Doe",
    "roles": [
      "foo"
    ]
  }'

Delete User

Delete a user from an organization.

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

Arguments

  • userrequiredstring(in path)

    user email

Response

  • dataoptionalobject

    User object that was deleted.

    Show child attributes

Example Request
Example Response
curl --request DELETE \
    --url https://api.usw2a1.rockset.com/v1/orgs/self/users/admin@me.com \
    -H 'Authorization: ApiKey _insert_your_apikey_here_'

List Users

Retrieve all users for an organization.

GET /v1/orgs/self/users

Arguments

    No arguments.

Response

  • dataoptionalobject array

    List of users.

    Show child attributes

Example Request
Example Response
curl --request GET \
    --url https://api.usw2a1.rockset.com/v1/orgs/self/users \
    -H 'Authorization: ApiKey _insert_your_apikey_here_'

Retrieve Current User

Retrieve currently authenticated user.

GET /v1/orgs/self/users/self

Arguments

    No arguments.

Response

  • emailrequiredstring

    User email.

  • created_atoptionalstring

    ISO-8601 date.

  • first_nameoptionalstring

    User first name.

  • last_nameoptionalstring

    User last name.

  • rolesoptionalstring array

    List of roles for a given user.

  • stateoptionalstring

    State of user - NEW / ACTIVE.

Example Request
Example Response
curl --request GET \
    --url https://api.usw2a1.rockset.com/v1/orgs/self/users/self \
    -H 'Authorization: ApiKey _insert_your_apikey_here_'

Retrieve Notification Preferences

Get all notification preferences.

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

Arguments

    No arguments.

Response

  • dataoptionalobject array

    List of notification preferences.

    Show child attributes

Example Request
Example Response
curl --request GET \
    --url https://api.usw2a1.rockset.com/v1/orgs/self/users/self/preferences \
    -H 'Authorization: ApiKey _insert_your_apikey_here_'

Retrieve User

Retrieve user by email.

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

Arguments

  • userrequiredstring(in path)

    user email

Response

  • emailrequiredstring

    User email.

  • created_atoptionalstring

    ISO-8601 date.

  • first_nameoptionalstring

    User first name.

  • last_nameoptionalstring

    User last name.

  • rolesoptionalstring array

    List of roles for a given user.

  • stateoptionalstring

    State of user - NEW / ACTIVE.

Example Request
Example Response
curl --request GET \
    --url https://api.usw2a1.rockset.com/v1/orgs/self/users/admin@me.com \
    -H 'Authorization: ApiKey _insert_your_apikey_here_'

Update Notification Preferences

Update notification preference.

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

Arguments

  • dataoptionalobject array

    List of notification preferences.

    Show child attributes

Response

  • dataoptionalobject array

    List of notification preferences.

    Show child attributes

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

Update User

Update a user in an organization.

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

Arguments

  • userrequiredstring(in path)

    email of the user to update

  • first_nameoptionalstring

    User first name.

  • last_nameoptionalstring

    User last name.

  • rolesoptionalstring array

    New list of roles for a given user.

Response

  • emailrequiredstring

    User email.

  • created_atoptionalstring

    ISO-8601 date.

  • first_nameoptionalstring

    User first name.

  • last_nameoptionalstring

    User last name.

  • rolesoptionalstring array

    List of roles for a given user.

  • stateoptionalstring

    State of user - NEW / ACTIVE.

Example Request
Example Response
curl --request POST \
    --url https://api.usw2a1.rockset.com/v1/orgs/self/users/admin@me.com \
    -H 'Authorization: ApiKey _insert_your_apikey_here_' \
  -H 'Content-Type: application/json' \
    -d '{
    "first_name": "John",
    "last_name": "Doe",
    "roles": [
      "foo"
    ]
  }'

Views

Create View

Create a view

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

Arguments

  • workspacerequiredstring(in path)

    name of the workspace

  • namerequiredstring

    View name.

  • queryrequiredstring

    SQL for this view.

  • descriptionoptionalstring

    Optional description.

Response

  • dataoptionalobject

    View that was updated.

    Show child attributes

Example Request
Example Response
curl --request POST \
    --url https://api.usw2a1.rockset.com/v1/orgs/self/ws/commons/views \
    -H 'Authorization: ApiKey _insert_your_apikey_here_' \
  -H 'Content-Type: application/json' \
    -d '{
    "description": "view of awesome collection",
    "name": "myAwesomeView",
    "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

Response

  • dataoptionalobject

    View that was deleted.

    Show child attributes

Example Request
Example Response
curl --request DELETE \
    --url https://api.usw2a1.rockset.com/v1/orgs/self/ws/commons/views/view \
    -H 'Authorization: ApiKey _insert_your_apikey_here_'

List Views

Retrieve all views in an organization

GET /v1/orgs/self/views

Arguments

    No arguments.

Response

  • dataoptionalobject array

    List of all views.

    Show child attributes

Example Request
Example Response
curl --request GET \
    --url https://api.usw2a1.rockset.com/v1/orgs/self/views \
    -H 'Authorization: ApiKey _insert_your_apikey_here_'

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

Response

  • dataoptionalobject array

    List of all views.

    Show child attributes

Example Request
Example Response
curl --request GET \
    --url https://api.usw2a1.rockset.com/v1/orgs/self/ws/commons/views \
    -H 'Authorization: ApiKey _insert_your_apikey_here_'

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

Response

  • dataoptionalobject

    View that was requested.

    Show child attributes

Example Request
Example Response
curl --request GET \
    --url https://api.usw2a1.rockset.com/v1/orgs/self/ws/commons/views/view \
    -H 'Authorization: ApiKey _insert_your_apikey_here_'

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

  • queryrequiredstring

    SQL for this view.

  • descriptionoptionalstring

    Optional description.

Response

  • dataoptionalobject

    View that was updated.

    Show child attributes

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

Virtual Instances

Create Virtual Instance

Create virtual instance

POST /v1/orgs/self/virtualinstances

Arguments

  • namerequiredstring

    Unique identifier for virtual instance, can contain alphanumeric or dash characters.

  • auto_suspend_secondsoptionalinteger

    Number of seconds without queries after which the VI is suspended

  • descriptionoptionalstring

    Description of requested virtual instance.

  • enable_remount_on_resumeoptionalboolean

    When a Virtual Instance is resumed, it will remount all collections that were mounted when the Virtual Instance was suspended.

  • mount_refresh_interval_secondsoptionalinteger

    Number of seconds between data refreshes for mounts on this Virtual Instance. A value of 0 means continuous refresh and a value of null means never refresh.

  • typeoptionalstring

    Requested virtual instance type. Possible values: FREE, NANO, SHARED, MILLI, SMALL, MEDIUM, LARGE, XLARGE, XLARGE2, XLARGE4, XLARGE8, XLARGE16.

Response

  • dataoptionalobject

    Virtual instance object.

    Show child attributes

Example Request
Example Response
curl --request POST \
    --url https://api.usw2a1.rockset.com/v1/orgs/self/virtualinstances \
    -H 'Authorization: ApiKey _insert_your_apikey_here_' \
  -H 'Content-Type: application/json' \
    -d '{
    "auto_suspend_seconds": 3600,
    "description": "VI serving prod traffic",
    "enable_remount_on_resume": true,
    "mount_refresh_interval_seconds": 3600,
    "name": "prod_vi",
    "type": "LARGE"
  }'

Delete Virtual Instance

Delete a virtual instance.

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

Arguments

  • virtualInstanceIdrequiredstring(in path)

    Virtual Instance RRN

Response

  • dataoptionalobject

    Virtual instance that was deleted.

    Show child attributes

Example Request
Example Response
curl --request DELETE \
    --url https://api.usw2a1.rockset.com/v1/orgs/self/virtualinstances/virtualInstanceId \
    -H 'Authorization: ApiKey _insert_your_apikey_here_'

Execute SQL Query

Make a SQL query to Rockset.

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

Arguments

  • virtualInstanceIdrequiredstring(in path)

    Virtual Instance RRN

  • sqlrequiredobject

    Main query request body.

    Show child attributes

  • asyncoptionalboolean

    If true, the query will run asynchronously for up to 30 minutes. The query request will immediately return with a query id that can be used to retrieve the query status and results. If false or not specified, the query will return with results once completed or timeout after 2 minutes. (To return results directly for shorter queries while still allowing a timeout of up to 30 minutes, set async_options.client_timeout_ms.)

  • async_optionsoptionalobject

    Options for configuring Asynchronous Query Mode.

    Show child attributes

  • debug_threshold_msoptionalinteger

    If query execution takes longer than this value, debug information will be logged. If the query text includes the DEBUG hint and this parameter is also provided, only this value will be used and the DEBUG hint will be ignored.

  • max_initial_resultsoptionalinteger

    This limits the maximum number of results in the initial response. A pagination cursor is returned if the number of results exceeds max_initial_results. If max_initial_results is not set, all results will be returned in the initial response up to 4 million. If max_initial_results is set, the value must be between 0 and 100,000. If the query is async and client_timeout_ms is exceeded, max_initial_results does not apply since none of the results will be returned with the initial response.

  • timeout_msoptionalinteger

    If a query exceeds the specified timeout, the query will automatically stop and return an error. The query timeout defaults to a maximum of 2 minutes. If async is true, the query timeout defaults to a maximum of 30 minutes.

Response

  • collectionsoptionalstring array

    List of collections referenced in the query.

  • column_fieldsoptionalobject array

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

    Show child attributes

  • last_offsetoptionalstring

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

  • paginationoptionalobject

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

    Show child attributes

  • query_errorsoptionalobject array

    Errors encountered while executing the query.

    Show child attributes

  • query_idoptionalstring

    Unique ID for this query.

  • query_lambda_pathoptionalstring

    The full path of the executed query lambda. Includes version information.

  • resultsoptionalobject array

    Results from the query.

  • results_total_doc_countoptionalinteger

    Number of results generated by the query.

  • statsoptionalobject

    Meta information about the query including execution latencies.

    Show child attributes

  • statusoptionalstring

    Status of query execution. Possible values: QUEUED, RUNNING, COMPLETED, ERROR. Possible values: QUEUED, RUNNING, COMPLETED, ERROR.

  • warningsoptionalstring array
Example Request
Example Response
curl --request POST \
    --url https://api.usw2a1.rockset.com/v1/orgs/self/virtualinstances/virtualInstanceId/queries \
    -H 'Authorization: ApiKey _insert_your_apikey_here_' \
  -H 'Content-Type: application/json' \
    -d '{
    "async": "true",
    "async_options": {
      "client_timeout_ms": "123"
    },
    "debug_threshold_ms": "123",
    "max_initial_results": "123",
    "sql": {
      "default_row_limit": "123",
      "parameters": [
        {
          "name": "_id",
          "value": "85beb391"
        }
      ],
      "query": "SELECT * FROM foo where _id = :_id"
    },
    "timeout_ms": "123"
  }'

Get Collection Commit

Determines if the collection includes data at or after the specified fence(s) for close read-after-write semantics.

POST /v1/orgs/self/virtualinstances/{virtualInstanceId}/mounts/{collectionPath}/offsets/commit

Arguments

  • virtualInstanceIdrequiredstring(in path)

    Virtual Instance RRN

  • collectionPathrequiredstring(in path)
  • nameoptionalstring array

    a list of zero or more collection offset fences

Response

  • dataoptionalobject

    Show child attributes

  • offsetsoptionalobject

    Show child attributes

Example Request
Example Response
curl --request POST \
    --url https://api.usw2a1.rockset.com/v1/orgs/self/virtualinstances/virtualInstanceId/mounts/collectionPath/offsets/commit \
    -H 'Authorization: ApiKey _insert_your_apikey_here_' \
  -H 'Content-Type: application/json' \
    -d '{
    "name": [
      "foo"
    ]
  }'

Get Collection Mount

Retrieve a mount on this virtual instance.

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

Arguments

  • virtualInstanceIdrequiredstring(in path)

    Virtual Instance RRN

  • collectionPathrequiredstring(in path)

Response

  • dataoptionalobject

    Resource mount object.

    Show child attributes

Example Request
Example Response
curl --request GET \
    --url https://api.usw2a1.rockset.com/v1/orgs/self/virtualinstances/virtualInstanceId/mounts/collectionPath \
    -H 'Authorization: ApiKey _insert_your_apikey_here_'

List Collection Mounts

List collection mounts for a particular VI.

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

Arguments

  • virtualInstanceIdrequiredstring(in path)

    Virtual Instance RRN

Response

  • dataoptionalobject array

    List of all collection mounts.

    Show child attributes

Example Request
Example Response
curl --request GET \
    --url https://api.usw2a1.rockset.com/v1/orgs/self/virtualinstances/virtualInstanceId/mounts \
    -H 'Authorization: ApiKey _insert_your_apikey_here_'

List Queries

Lists actively queued and running queries for a particular Virtual Instance.

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

Arguments

  • virtualInstanceIdrequiredstring(in path)

    Virtual Instance RRN

Response

  • dataoptionalobject array

    Show child attributes

Example Request
Example Response
curl --request GET \
    --url https://api.usw2a1.rockset.com/v1/orgs/self/virtualinstances/virtualInstanceId/queries \
    -H 'Authorization: ApiKey _insert_your_apikey_here_'

List Virtual Instances

Retrieve all virtual instances in an organization.

GET /v1/orgs/self/virtualinstances

Arguments

    No arguments.

Response

  • dataoptionalobject array

    List of all virtual instances.

    Show child attributes

Example Request
Example Response
curl --request GET \
    --url https://api.usw2a1.rockset.com/v1/orgs/self/virtualinstances \
    -H 'Authorization: ApiKey _insert_your_apikey_here_'

Mount Collections

Mount a collection to this virtual instance.

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

Arguments

  • virtualInstanceIdrequiredstring(in path)

    Virtual Instance RRN

  • collection_pathsoptionalstring array

    Collections to mount.

Response

  • dataoptionalobject array

    Mounts created.

    Show child attributes

Example Request
Example Response
curl --request POST \
    --url https://api.usw2a1.rockset.com/v1/orgs/self/virtualinstances/virtualInstanceId/mounts \
    -H 'Authorization: ApiKey _insert_your_apikey_here_' \
  -H 'Content-Type: application/json' \
    -d '{
    "collection_paths": [
      "foo"
    ]
  }'

Resume Virtual Instance

Resume a virtual instance.

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

Arguments

  • virtualInstanceIdrequiredstring(in path)

    Virtual Instance RRN

Response

  • dataoptionalobject

    Virtual instance that was resumed.

    Show child attributes

Example Request
Example Response
curl --request POST \
    --url https://api.usw2a1.rockset.com/v1/orgs/self/virtualinstances/virtualInstanceId/resume \
    -H 'Authorization: ApiKey _insert_your_apikey_here_'

Retrieve Virtual Instance

Get details about a virtual instance.

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

Arguments

  • virtualInstanceIdrequiredstring(in path)

    Virtual Instance RRN

Response

  • dataoptionalobject

    Virtual instance that was requested.

    Show child attributes

Example Request
Example Response
curl --request GET \
    --url https://api.usw2a1.rockset.com/v1/orgs/self/virtualinstances/virtualInstanceId \
    -H 'Authorization: ApiKey _insert_your_apikey_here_'

Suspend Virtual Instance

Suspend a virtual instance.

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

Arguments

  • virtualInstanceIdrequiredstring(in path)

    Virtual Instance RRN

Response

  • dataoptionalobject

    Virtual instance that was suspended.

    Show child attributes

Example Request
Example Response
curl --request POST \
    --url https://api.usw2a1.rockset.com/v1/orgs/self/virtualinstances/virtualInstanceId/suspend \
    -H 'Authorization: ApiKey _insert_your_apikey_here_'

Unmount Collection

Unmount a collection from this virtual instance.

DELETE /v1/orgs/self/virtualinstances/{virtualInstanceId}/mounts/{collectionPath}

Arguments

  • virtualInstanceIdrequiredstring(in path)

    Virtual Instance RRN

  • collectionPathrequiredstring(in path)

Response

  • dataoptionalobject

    Resource mount object.

    Show child attributes

Example Request
Example Response
curl --request DELETE \
    --url https://api.usw2a1.rockset.com/v1/orgs/self/virtualinstances/virtualInstanceId/mounts/collectionPath \
    -H 'Authorization: ApiKey _insert_your_apikey_here_'

Update Virtual Instance

Update the properties of a virtual instance.

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

Arguments

  • virtualInstanceIdrequiredstring(in path)

    Virtual Instance RRN

  • auto_scaling_policyoptionalobject

    Options for configuring auto scaling policy

    Show child attributes

  • auto_suspend_enabledoptionalboolean

    Whether auto-suspend should be enabled for this Virtual Instance.

  • auto_suspend_secondsoptionalinteger

    Number of seconds without queries after which the VI is suspended

  • descriptionoptionalstring

    New virtual instance description.

  • enable_remount_on_resumeoptionalboolean

    When a Virtual Instance is resumed, it will remount all collections that were mounted when the Virtual Instance was suspended.

  • mount_refresh_interval_secondsoptionalinteger

    Number of seconds between data refreshes for mounts on this Virtual Instance. A value of 0 means continuous refresh and a value of null means never refresh.

  • nameoptionalstring

    New virtual instance name.

  • new_sizeoptionalstring

    Requested virtual instance size. Possible values: FREE, NANO, SHARED, MILLI, SMALL, MEDIUM, LARGE, XLARGE, XLARGE2, XLARGE4, XLARGE8, XLARGE16.

Response

  • dataoptionalobject

    Virtual instance that was switched.

    Show child attributes

Example Request
Example Response
curl --request POST \
    --url https://api.usw2a1.rockset.com/v1/orgs/self/virtualinstances/virtualInstanceId \
    -H 'Authorization: ApiKey _insert_your_apikey_here_' \
  -H 'Content-Type: application/json' \
    -d '{
    "auto_scaling_policy": {
      "enabled": true,
      "max_size": "XLARGE2",
      "min_size": "LARGE"
    },
    "auto_suspend_enabled": true,
    "auto_suspend_seconds": 3600,
    "description": "VI for prod traffic",
    "enable_remount_on_resume": true,
    "mount_refresh_interval_seconds": 3600,
    "name": "prod_vi",
    "new_size": "LARGE"
  }'

Workspaces

Create Workspace

Create a new workspace.

POST /v1/orgs/self/ws

Arguments

  • namerequiredstring

    Descriptive label and unique identifier.

  • descriptionoptionalstring

    Longer explanation for the workspace.

Response

  • dataoptionalobject

    The workspace that was created.

    Show child attributes

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

Delete Workspace

Remove a workspace.

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

Arguments

  • workspacerequiredstring(in path)

    name of the workspace

Response

  • dataoptionalobject

    The workspace that was deleted.

    Show child attributes

Example Request
Example Response
curl --request DELETE \
    --url https://api.usw2a1.rockset.com/v1/orgs/self/ws/commons \
    -H 'Authorization: ApiKey _insert_your_apikey_here_'

List Workspaces

List all workspaces in an organization.

GET /v1/orgs/self/ws

Arguments

    No arguments.

Response

  • dataoptionalobject array

    List of workspaces.

    Show child attributes

Example Request
Example Response
curl --request GET \
    --url https://api.usw2a1.rockset.com/v1/orgs/self/ws \
    -H 'Authorization: ApiKey _insert_your_apikey_here_'

Retrieve Workspace

Get information about a single workspace.

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

Arguments

  • workspacerequiredstring(in path)

    name of the workspace

Response

  • dataoptionalobject

    The workspace that was requested.

    Show child attributes

Example Request
Example Response
curl --request GET \
    --url https://api.usw2a1.rockset.com/v1/orgs/self/ws/commons \
    -H 'Authorization: ApiKey _insert_your_apikey_here_'
Ask the CommunityContact SupportReport Docs Issue
Copyright © 2023 Rockset