Default Query Virtual Instance


Default Query Virtual Instance is currently in Beta.

Every Rockset organization starts with one Virtual Instance per active deployment (where a deployment refers to each region where your organization has been set up). This Virtual Instance, referred to as the main Virtual Instance in this section, handles all streaming ingest and queries by default. Rockset supports creating additional Virtual Instances, which can help distribute load and isolate your workloads. Currently, these additional Virtual Instances do not handle streaming ingest, but can be used to query any Collections that are mounted to them.

When running queries and Query Lambdas on Rockset, you have the capability to specify the Virtual Instance you’d like the query to run on (see the API documentation for queries and query lambdas for examples). If your deployment has multiple Virtual Instances and you execute a query without specifying a Virtual Instance (for example, by sending a request to the execute SQL query endpoint), the query will run on the Virtual Instance that is designated as the default query Virtual Instance within the deployment. To begin with, this is always the main Virtual Instance, but when running multiple Virtual Instances we recommend updating the setting so that your queries will run on a different Virtual Instance by default. Setting up a dedicated default query Virtual Instance has the benefit of isolating your ingest and query workloads from each other, and will allow you to tune your Virtual Instances to handle specific workloads and reduce costs. For example, this feature can be coupled with Micro-Batching for your ingest Virtual Instance. Micro-batching allows your ingest Virtual Instance to be auto-suspended and resumed when certain criteria are met, saving compute costs, while queries can still be served on the default query Virtual Instance.

Configuring your deployment default Virtual Instance

Prerequisites: You will need the UPDATE_DEPLOYMENT_DEFAULT_QUERY_VI permission in order to manage the deployment default Virtual Instance setting. The built-in Admin role has this permission but the Member and Read-only roles do not.

Things to Know

There are some things to note about using the Default Query Virtual Instance setting:

  • This setting affects requests made to the /v1/orgs/self/queries and /v1/orgs/self/ws/{workspace}/lambdas/{queryLambda} endpoints.
  • The default query Virtual Instance setting does not affect RBAC settings, so any user that does not have permission to run queries on this Virtual Instance will need to specify a different Virtual Instance (that they have sufficient permissions for) in order to run queries or query lambdas.
  • The default query Virtual Instance is allowed to be suspended. All queries that are run on the default query Virtual Instance will fail if it is suspended.
  • You are not allowed to delete your default query Virtual Instance. If you attempt to do so, we will prompt you to update the default query Virtual Instance setting to a different Virtual Instance before you can perform the deletion.
  • You will not be able to enable micro-batching on your ingest Virtual Instance if it is currently set as the default query Virtual Instance, and you will not be able to set a Virtual Instance to be the default query Virtual Instance if it has micro-batching enabled.

Managing the setting in the Rockset Console

The default query Virtual Instance is initially set to your main Virtual Instance. You can update this setting via the Rockset Console, under the Virtual Instances page. When configuring your default query Virtual Instance, you can select an existing Virtual Instance or create a new one. If you select a currently suspended Virtual Instance, it will be resumed so that queries can run against it. You will also be able to select the desired size, auto-suspend interval, and any collections to mount for the Virtual Instance. Some recommendations on the values to use for each of these settings:

Virtual Instance Size

To begin with, we recommend setting your default query Virtual Instance to the same size as your main Virtual Instance. Based on observed CPU and memory utilization, you can then scale down both Virtual Instances. If your organization has access to the auto-scaling feature, you can enable this as well (currently only available for ingest Virtual Instances).

Auto-Suspend Interval

We recommend setting the Auto-Suspend Interval to Never on your default query Virtual Instance. If you set an auto-suspend policy on this Virtual Instance, any queries run against the default query Virtual Instance will fail while the Virtual Instance is suspended.


You will not be able to query any collections that are not mounted, so you should ensure that you have mounted all collections needed for queries that are running on your current default query Virtual Instance. New collections will automatically be mounted to your default query Virtual Instance.

Managing the setting via the Rockset API

You can also manage this setting via the API. Example request:

curl --request PUT \
    --url https://$ROCKSET_SERVER/v1/orgs/self/deploymentsettings \
    -H 'Authorization: ApiKey $API_KEY' \
    -H 'Content-Type: application/json' \
    -d '{
	    "default_query_vi": "$VI_RRN"

If using the API rather than the UI, you will need to manually resume the Virtual Instance if it is suspended, as well as update the size and auto-suspend interval if desired, and mount any collections you want to query to the Virtual Instance.

For more details, see the API documentation.