ID Clause (Reference)

Other filter operators generally look for particular JSON fields within the content of documents and try to match their values. An ID clause , which uses operator $id, instead matches document keys. It thus matches document metadata, not document content.

Operator $id is not supported by SODA for Java or SODA for REST for use with a heterogeneous collection, that is, a collection that has the media type column..

A document key uniquely identifies a given document. It is metadata, like the creation time stamp, last-modified time stamp, and version. It pertains to the document as a whole and is not part of the document content.

The syntax of an ID clause is filter operator $id followed by either a scalar key (document identifier) or a non-empty array of scalar keys.¹ The scalar key must be either an integer or a string. The array elements must be either all integers or all strings. For example:

"$id" : "USA"
"$id" : [1001,1002,1003]

Like a special-criterion clause or a text-contains clause, you can use operator $id only in the outermost condition of a filter, that is, in a condition used in a composite filter or in a filter-condition filter.

An ID clause can be combined with other clauses in a $and clause. Only a single ID clause can be combined with other clauses in the same filter.

Example 5-3 Use of Operator $id in the Outermost Filter Condition

Each of these equivalent filters finds documents that have at least one of the keys key1 and key2, and that have a color field with value "red". (Operator $and is implicit in the first filter.)

{ "$id" : [ "key1", "key2" ], "color" : "red" }
{ "$and" : [ { "$id" : [ "key1", "key2" ] }, { "color" : "red" } ] }
{ "$and" : [ { "$id" : [ "key1", "key2" ], "color" : "red" } ] }

Related Topics

• Overview of Filer Operator $id

• Special-Criterion Clause (Reference)

1. A syntax error is raised if the array does not contain at least one element. ↩