Search Queries

You can use the SEARCH keyword to filter a query using a search view, allowing you to:

• Filter documents based on C8QL and SQL Boolean expressions and functions.
• Match documents located in different collections.
• Sort the result set based on how closely each document matches the search conditions.

For information about creating a custom search view, refer to Search Views.

Syntax

You must use the SEARCH statement in a FOR...IN operation. The SEARCH statement must be placed after the FOR and before any additional operations.

FOR doc IN <SEARCH_VIEW_NAME>
  SEARCH <EXPRESSION> OPTIONS {…}
  ...

Replace SEARCH_VIEW_NAME with the name of your search view, and EXPRESSION with one of the following functions:

• AND
• OR
• NOT
• ==
• <=
• >=
• <
• >
• !=
• IN (array or range), also NOT IN

For example:

FOR doc IN MySearchView
  SEARCH ANALYZER(doc.text == "quick" OR doc.text == "brown", "text_en") OPTIONS { collections: ["coll1", "coll2"] }
RETURN doc

Limitations

SEARCH does not support:

• Alphabetical order
• Array comparison operators
• Inline expressions

Refer to Search Options for information about the OPTIONS keyword.

Search by Document Attribute

You can search for documents by querying document attributes that have been indexed by both the search view and the document store. Refer to Document Store Indexes for more information about adding attributes to document store indexes.

When you search for a document by its attribute, all attributes (including non-indexed ones) return in the results. However, querying a non-indexed attribute yields no results.

For example, if you have documents in a collection with these attributes:

{ "someAttr": "One", "anotherAttr": "One" }
{ "someAttr": "Two", "anotherAttr": "Two" }

Only the someAttr attribute is indexed in the search view and the document store index.

You can run this query to return all attributes for the first document in the collection:

FOR doc IN MySearchView
  SEARCH doc.someAttr == "One"
  RETURN doc

The result displays all attributes for the first document, including the non-indexed anotherAttr.

Alternatively, if you query by the non-indexed anotherAttr attribute, the search yields no results:

FOR doc IN myView
  SEARCH doc.anotherAttr == "One"
  RETURN doc

You can use the includeAllFields View property to index all fields and subfields of the source documents.

Search for Array Elements

You can search for individual array elements if your search view has trackListPositions set to true.

In the following document, the values 1, 2, and 3 are indexed and individually searchable.

{
  "value": {
    "nested": {
      "deep": [ 1, 2, 3 ]
    }
  }
}

If your search view indexes the value field, you can use a query such as doc.value.nested.deep:

FOR doc IN viewName
  SEARCH doc.value.nested.deep == 2
  RETURN doc

Alternatively, you can use an array comparison operator with a FILTER operation:

FOR doc IN collection
  FILTER doc.value.nested.deep ANY == 2
  RETURN doc

If trackListPositions is disabled on the search view, then you must specify the position within the array of the data you want to find. For example:

FOR doc IN viewName
  SEARCH doc.value.nested.deep[1] == 2
  RETURN doc

In this example, [1] indicates that the desired result (2) is the second value in the array. If you wanted to find the first value, you would instead use:

SEARCH doc.value.nested.deep[0] == 1

Search with SORT()

You can retrieve documents that aren't indexed by the search view with the SORT() operation. For example:

FOR doc IN viewName
  SORT doc.text, doc.value DESC
  RETURN doc

You can also use Search Scoring Functions to sort the retrieved documents by relevance. This only works for documents excluded from the search view's index. For example:

FOR doc IN viewName
  SEARCH ...
  SORT BM25(doc) DESC
  RETURN doc

Search Options

SEARCH also accepts the following optional attribute:

• collections (array): Array of strings with collection names to restrict the search to certain source collections.

If a search view has three linked collections (coll1, coll2, and coll3), you can return documents from specific collections with the collections option:

FOR doc IN viewName
  SEARCH true OPTIONS { collections: ["coll1", "coll2"] }
  RETURN doc

Alternatively, you can replace true with false to exclude the specified collections.