• Querying Your Data
  • Query Lambdas

Query Lambdas

Query Lambdas are named, parameterized SQL queries stored in Rockset that can be executed from a dedicated REST endpoint. Using Query Lambdas, you can save your SQL queries as separate resources in Rockset and manage them successfully through development and production.

#Why Query Lambdas?

We recommend using Query Lambdas to build applications backed by Rockset as opposed to querying with raw SQL directly from application code. See our release blog for the full story on how Query Lambdas can increase developer velocity in your application development.

#Version Control SQL Queries

Each Query Lambda maintains a version history and programmatic executions of that Lambda must provide a version. Any update to a Query Lambda automatically creates a new version. Versioning allows you to build and test changes without affecting production queries. Each Query Lambda - Version pair is immutable, so once specified in application code the underlying query will never change without the application source code itself changing.

Learn more about enforcing version control with Query Lambdas here.

#Manage the SQL Development Lifecycle

Working with raw SQL is dangerous and tedious enough as-is, especially when embedding it into application code. Avoid SQL injection security risks and potential schema exposure by saving your queries and turning them into REST endpoints. Once a Query Lambda is created, a REST endpoint is automatically generated which you can then query directly with your query parameters as HTTP parameters. Collaborating on SQL queries is now as easy as sharing a link, while your application code remains unchanged.

#Monitor Individual Query Metrics

Without custom implementation work application-side, there is no way to understand how a particular query is performing. Now that your SQL queries are saved as abstracted resources in Rockset, however, you can monitor and track their performance as they are executed in production. Rockset automatically maintains several statistics and performance metrics for each of your Query Lambdas.

Learn more about performance monitoring and errors with Query Lambdas here.

#Creating Query Lambdas

Query Lambdas can be created and updated in the Query Lambdas tab of the Rockset Console or by using the Rockset API directly. Our official client libraries also natively support creating Query Lambdas. See library-specific documentation for relevant syntax.

Each Query Lambda is tied to a specific query text and parameter set. You can set default values for query parameters (making them optional during executions of your query Lambda), or you can make them mandatory for each execution (failing to pass along will result in an error).

For example, the following basic query can be saved as a Query Lambda:

SELECT
    :echo as echo

As part of the Query Lambda creation process you would specify parameter echo and optionally provide a default value (for this example, let’s assume a default value of "Hello, world!"). We can save this SQL / parameter pair as a Query Lambda called helloWorldLambda, and then execute it through a REST endpoint from anywhere (given an API key):

curl --request POST \
  --url https://api.rs2.usw2.rockset.com/v1/orgs/self/ws/commons/lambdas/helloWorldLambda/versions/{version} \
  -H 'Authorization: ApiKey ...' -H 'Content-Type: application/json'
>>> [{ "echo": "Hello, world!" }]

curl --request POST \
  --url https://api.rs2.usw2.rockset.com/v1/orgs/self/ws/commons/lambdas/helloWorldLambda/versions/{version} \
  -H 'Authorization: ApiKey ...' -H 'Content-Type: application/json'
  -d '{
    "parameters": [
      {
        "name": "echo",
        "value": "Hola, mundo!"
      }
    ]
  }'
>>> [{ "echo": "Hola, mundo!" }]

#Using Query Lambdas with Workspaces

Like Collections, each Query Lambda is associated with a particular workspace (by default, they will be created in the commons workspace). You can set this workspace at the time of creation.

Note that Query Lambdas in one workspace are not limited to querying collections in that same workspace. Any Query Lambda in any workspace can query any number of collections in any number of workspaces within your Rockset organization.

#Executing Query Lambdas

Executing a Query Lambda is as easy as hitting its dedicated REST endpoint, which is automatically generated on creation (and each update). Each Query Lambda will generate a REST endpoint with the following format:

https://api.rs2.usw2.rockset.com/v1/orgs/self/ws/{workspace}/lambdas/{queryLambda}/versions/{version}

You can also find this URL by navigatin to the Query Lambdas tab of the Rockset Console and then selecting your newly created Query Lambda. There, you can find both the dedicated REST endpoint as well as instructions on how to execute the Query Lambda.

Query Lambda Endpoint

Execute the Query Lambda by hitting its dedicated REST endpoint with a POST request directly, passing in any query parameters as REST parameters as necessary.

Join us on Slack!
Building on Rockset? Come chat with us!