Concepts > Query Lambdas

Query Lambdas

Query Lambdas are named parameterized SQL queries stored in Rockset that can be executed from a dedicated REST endpoint. We recommend using Query Lambdas to build applications backed by Rockset as opposed to querying with raw SQL directly from application code. The advantages of doing so are described below.

Features

Store SQL text and parameter information

Query Lambdas can be created and updated using the Rockset Console or by using the REST API directly. 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).

Expose a REST endpoint to execute underlying query

Each Query Lambda is exposed as its own endpoint. For example, the following basic query can be saved as a Query Lambda:

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/1 \
  -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/1 \
  -H 'Authorization: ApiKey ...' -H 'Content-Type: application/json'
  -d '{
    "parameters": [
      {
        "name": "echo",
        "value": "Hola, mundo!"
      }
    ]
  }'
>>> [{ "echo": "Hola, mundo!" }]

Enforce version control

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.

Organize by workspace

Just like Collections, each Query Lambda is associated with a particular workspace (by default, commons). You can set this workspace at the time of creation. Query Lambda’s in one workspace are not limited to querying collections in that same workspace.

Expose usage metrics and statistics

Each version of of Query Lambda tracks and exposes a number of metrics. Currently supported metrics include:

  • Last Executed: time of last execution
  • Last Executed By: user id associated with last execution
  • Last Execution Error: time of last execution error
  • Last Execution Error Message: error message associated with last execution error

More to come soon.

Usage

Creating Query Lambdas

You can create Lambdas by saving query SQL as a Lambda from the Rockset Console or by creating directly via the REST API. From the Console Query Editor view, you can click the ‘Create Query Lambda’ button to create a Query Lambda. Any specified parameters will be added to the Query Lambda along with the SQL text.

You can also create Query Lambdas through the REST API.

Our API libraries also natively support creating Query Lambdas. See library-specific documentation for relevant syntax.

Executing Query Lambdas

Executing a Query Lambda is as easy as hitting its REST endpoint (passing parameters as options if necessary).

Our API libraries also natively support executing Query Lambdas. See library-specific documentation for relevant syntax.

Accessing Metrics and Statistics

Each Query Lambda version maintains certain metrics as described in the ‘Query Lambda Features’ section. You can see these metrics in the Rockset Console in the ‘Query Lambda’ tab.