SODA Filter Specifications (Reference)

The script content on this page is for navigation purposes only and does not alter the content in any way.

You can select JSON documents in a collection by pattern-matching. A detailed definition of SODA filter specifications is presented.

A filter specification , also known as simply a filter , is a SODA query that uses a pattern expressed in JSON. A filter is itself a JSON object. SODA query operations use a filter to select all JSON documents in a collection that satisfy it, meaning that the filter evaluates to true for only those documents. A filter thus specifies characteristics that the documents that satisfy it must possess.

A filter can use filter operators , which are predefined JSON fields whose names start with a dollar-sign character ($). The JSON value associated with an operator field is called its operand or its argument.1

Although a SODA operator is itself a JSON field, for ease of exposition in the context of filter specification descriptions, the term “field” generally refers here to a JSON field that is not a SODA operator. Also, in the context of a filter, “field” is often used informally to mean “path to a field”.

Note: You must use strict JSON syntax in a SODA filter specification, enclosing each nonnumeric, non-Boolean, and non-null JSON value in double quotation marks ("). In particular, the names of all JSON fields, including SODA operators, must be enclosed in double quotation marks.

A filter specification is a JSON object. There are two kinds of filter specification:

A filter specification can appear only at the top (root) level of a query. However, a filter condition can be used either (a) on its own, as a filter-condition filter, or (b) at a lower level, in the query clause of a composite filter.

Note: In general, filter is for querying JSON documents. Filter operators $id and $textContains can exceptionally be used with a heterogeneous collection, that is, a collection that has the media type column. Operator $textContains can only be used with a heterogeneous collection. (A heterogeneous collection can, but it need not, contain JSON documents.) SODA for Java and SODA for REST do not support operator $textContains, and they do not support operator $id for use with a heterogeneous collection.

See Also: Oracle Database JSON Developer’s Guide for information about strict and lax JSON syntax

Related Topics

  1. A syntax error is raised if the argument to a filter operator is not of the required type (for example, if operator $gt is passed an argument that is not a string or a number). ↩