README

cosmosdb-query

A SQL parser and executer for Cosmos DB.

const { default: query } = require("@zeit/cosmosdb-query");

const items = [
  { id: "foo" },
  { id: "bar" }
];

const { result } = query("SELECT * FROM c WHERE c.id = @id")
  .exec(items, {
    parameters: [{ name: "@id", value: "foo" }]
  });
console.log(result); // [ { id: "foo" } ]

query(sql)

sql <string>
Returns: <Query>

const q = query("SELECT * FROM c")

Class: Query

q.exec(items[, options])

items <Object[]> | <null>
options <Object>
- parameters <Object[]> The parameters to pass to query
- udf <Object>
- maxItemCount <number> The number of items to return at a time
- continuation <Object> Continuation token
- compositeIndexes <Object[][]> Optional composite index definitions for validating multiple ORDER BY properties. By default, no definition is required and this value is used only for validation.
Returns: <Object>
- result <Object[]> Result documents
- continuation <Object> Continuation token for subsequent calls

Executes a query for items.

query(`SELECT VALUE udf.REGEX_MATCH("foobar", ".*bar")`).exec([], {
  udf: {
    REGEX_MATCH(input, pattern) {
      return input.match(pattern) !== null
    }
  }
});

When the maxItemCount and/or continuation options are used, all itesms have to contain the _rid field with unique values.

const items = [
  { _rid: "a", value: 1 },
  { _rid: "b", value: 2 },
  { _rid: "c", value: 3 }
];
const q = query(`SELECT * FROM c`);
const { result, continuation } = q.exec(items, { maxItemCount: 2 });
console.log(result); // [ { _rid: "a", value: 1 }, { _rid: "b", value: 2 } ]

const { result: result2 } = q.exec(items, { maxItemCount: 2, continuation });
console.log(result2); // [ { _rid: "c", value: 3 } ]

q.containsPartitionKeys(keys)

keys <string[]>
Returns: <boolean>

Determines whether query may contain partition keys.

const q = query("SELECT * FROM c WHERE c.id = 1");
if (!q.containsPartitionKeys(["/key"])) {
  throw new Error("query doesn't contain partition keys");
}

q.ast

<Object>

The AST object of query.

Class: SyntaxError

const { default: query, SyntaxError } = require("@zeit/cosmosdb-query");

try {
  query("INVALID SELECT").exec(items);
} catch (err) {
  if (err instanceof SyntaxError) {
    console.error(err);
  }
  throw err;
}

Supported queries

All queries are supported except spatial functions ST_ISVALID and ST_ISVALIDDETAILED.

The spatial functions ST_INTERSECTS, ST_WITHIN, and ST_DISTANCE are supported; use parameters to pass in GeoJSON as strings. Items in collections that are GeoJSON are expected to be of type string.

Usage no npm install needed!