CipherStash
CipherStash Documentation

Searching your collections with Stash CLI

All searching of data in a workspace is performed using the stash query command. In order to successfully search, you must be logged in (stash-login.md).

To perform a query, you need to specify at least the collection you wish to search. In addition, you will also usually want to specify a set of conditions which documents must satisfy in order to be returned.

Synopsis

stash query --collection <collection> \
    [--where <filter>] \
    [--limit <limit>] \
    [--format <format>] \
    [--var <name>=<value>] ...

Options

  • --collection <collection> (required) the name of the collection within the workspace to be searched.

  • --where <filter> (optional; default "") the conditions that must be met by a document in order for it to be returned in the search. If no filter is specified, then all documents will be returned, in no particular order. For details of the structure of filters, see the section “Filter Syntax”, below.

  • --var <name>=<value> (optional; repeated) assign a value to a variable placeholder within the filter. See the section “Filter Variables” for details.

  • --limit <limit> (optional; default 50) the maximum number of documents to be returned by the search. The hard upper limit on this value is 1000.

  • --format <format> (optional; default "table") the format used to output the search results. Can be one of "table" or "json".

Filter Syntax

A filter is a vaguely SQL-shaped specification of the conditions which must be satisfied in order for a document to be part of the query result set. It consists of a series of operations, combined by the AND operator.

Valid operations are listed below. In each case, <index> is the name of an index defined in the collection schema which supports the given operation, while variable placeholders (:<anything>) can be any valid variable name.

  • <index> eq :variable -- equality. Valid for Exact and Range indexes. The value of the index in the document must be equal to the value of the variable.

  • <index> lt :variable -- strictly-less-than. Valid for Range indexes. The value of the index in the document must sort before the value of the variable.

  • <index> lte :variable -- less-than-or-equal-to. Valid for Range indexes. The value of the index in the document must sort before, or be equal to, the value of the variable.

  • <index> gt :variable -- strictly-greater-than. Valid for Range indexes. The value of the index in the document must sort after the value of the variable.

  • <index> gte :variable -- greater-than-or-equal-to. Valid for Range indexes. The value of the index in the document must sort after, or be equal to, the value of the variable.

  • <index> match :variable -- full-text-match. Valid for Match and DynamicMatch indexes.

Filter Variables

In a filter, the value to be compared against is specified by means of a variable placeholder. A variable placeholder is a colon (:), followed by at least one alphanumeric character or underscore. During the query execution, these placeholders will be replaced with the variable values you specify with the --var flag.

Variables and their values are separated in filters to prevent what would be the CipherStash equivalent of an “SQL injection” attack. Since a CipherStash filter expression doesn’t mix syntax and data, there’s no opportunity for this class of attack. Naming variables also helps in making the meaning of your queries more obvious, if you choose meaningful variable names.

If your filter uses multiple variable placeholders (for example, foo eq :foo AND bar eq :bar), then you should use the --var flag multiple times to specify the value for each variable.

Examples

Find all movies that were made in or after 1995:

stash query --collection movies --where 'year >= :year' --var year=1995

Find all movies made in the 1980s that have the word “extreme” in their title:

stash query --collection movies \
    --where 'year >= :first_year AND year <= :last_year AND title match :title_word' \
    --var first_year=1980 \
    --var last_year=1989 \
    --var title_word=extreme

Exit Status

The exit status will be 0 if the query completes successfully, whether or not it matched any documents. An exit status of 1 indicates a problem with the inputs, for example if the filter is invalid, or a variable value is not specified. An exit status of 2 indicates a server-side failure to execute the query, most likely because the collection does not exist, credentials were invalid, or the server was unavailable.

Whenever a non-zero exit status is returned, a helpful error message is printed to standard error.