if not isinstance(val, bool):

raise ValueError(

'$exists operator can only accept True/False as value for comparison'

)

if '__' in get_key:

is_empty = False

try:

is_empty = not value

except:

# ndarray-like will end up here

pass

return is_empty != val

return (get_key in doc.non_empty_fields) == val

if not value or not isinstance(value, dict):

raise ValueError(

'''Not a valid query. It should follow the format:

)

items = list(value.items())

if len(items) == 1:

(doc-fields)=

(find-documentarray)=

We can use {meth}`~docarray.array.mixins.find.FindMixin.find` to select Documents from a DocumentArray based the conditions specified in a `query` object. One can use `da.find(query)` to filter Documents and get nearest neighbours from `da`:

- To filter Documents, the `query` object is a Python dictionary object that defines the filtering conditions using a [MongoDB](https://docs.mongodb.com/manual/reference/operator/query/)-like query language.

- To find nearest neighbours, the `query` object needs to be a NdArray-like, a Document, or a DocumentArray object that defines embedding. One can also use `.match()` function for this purpose, and there is a minor interface difference between these two functions, which will be described {ref}`in the next chapter<match-documentarray>`.

Let's see some examples in action. First, let's prepare a DocumentArray we will use.

from jina import Document, DocumentArray

da = DocumentArray([Document(text='journal', weight=25, tags={'h': 14, 'w': 21, 'uom': 'cm'}, modality='A'),

Document(text='notebook', weight=50, tags={'h': 8.5, 'w': 11, 'uom': 'in'}, modality='A'),

Document(text='paper', weight=100, tags={'h': 8.5, 'w': 11, 'uom': 'in'}, modality='D'),

Document(text='planner', weight=75, tags={'h': 22.85, 'w': 30, 'uom': 'cm'}, modality='D'),

Document(text='postcard', weight=45, tags={'h': 10, 'w': 15.25, 'uom': 'cm'}, modality='A')])

da.summary()

A query filter document can use the query operators to specify conditions in the following form:

Here `field1` is {ref}`any field name<doc-fields>` of a Document object. To access nested fields, one can use the dunder expression. For example, `tags__timestamp` is to access `doc.tags['timestamp']` field.

`value1` can be either a user given Python object, or a substitution field with curly bracket `{field}`

Finally, `operator1` can be one of the following:

| Query Operator | Description |

|----------------|------------------------------------------------------------------------------------------------------------|

| `$eq` | Equal to (number, string) |

| `$ne` | Not equal to (number, string) |

| `$gt` | Greater than (number) |

| `$gte` | Greater than or equal to (number) |

| `$lt` | Less than (number) |

| `$lte` | Less than or equal to (number) |

| `$in` | Is in an array |

| `$nin` | Not in an array |

| `$regex` | Match the specified regular expression |

| `$size` | Match array/dict field that have the specified size. `$size` does not accept ranges of values. |

| `$exists` | Matches documents that have the specified field. And empty string content is also considered as not exists. |

For example, to select all `modality='D'` Documents,

r = da.find({'modality': {'$eq': 'D'}})

pprint(r.to_dict(exclude_none=True)) # just for pretty print

To select all Documents whose `.tags['h']>10`,

r = da.find({'tags__h': {'$gt': 10}})

Beside using a predefined value, one can also use a substitution with `{field}`, notice the curly brackets there. For example,

r = da.find({'tags__h': {'$gt': '{tags__w}'}})

You can combine multiple conditions using the following operators

| Boolean Operator | Description |

|------------------|----------------------------------------------------|

| `$and` | Join query clauses with a logical AND |

| `$or` | Join query clauses with a logical OR |

| `$not` | Inverts the effect of a query expression |

r = da.find({'$or': [{'weight': {'$eq': 45}}, {'modality': {'$eq': 'D'}}]})

Once `.embeddings` is set, one can use {meth}`~docarray.array.mixins.find.FindMixin.find` or {func}`~docarray.array.mixins.match.MatchMixin.match` function to find the nearest-neighbour Documents from another DocumentArray (or itself) based on their `.embeddings` and distance metrics.

Though both `.find()` and `.match()` is about finding nearest neighbours of a given "query" and both accpet similar arguments, there are some differences between them:

- `.find()` always requires the query on the right-hand side. Say you have a DocumentArray with one million Documents, to find one query's nearest neightbours you should write `one_million_docs.find(query)`;

- `.match()` assumes the query is on left-hand side. `A.match(B)` semantically means "A matches against B and save the results to A". So with `.match()` you should write `query.match(one_million_docs)`.

- query (RHS) in `.find()` can be plain NdArray-like object or a single Document or a DocumentArray.

- query (lHS) in `.match()` can be either a Document or a DocumentArray.

- `.find()` returns a List of DocumentArray, each of which corresponds to one element/row in the query.

- `.match()` do not return anything. Match results are stored inside right-hand side's `.matches`.

In the example below, we will use `.match()` to describe the feature. But keep in mind, `.find()` should always work by simply switching the right and left-hand sides.

The above example when writing with `.find()`:

da2.find(da1, metric='euclidean', limit=3)

or simply:

da2.find(np.array(

[[0, 0, 0, 0, 1],

[1, 0, 0, 0, 0],

[1, 1, 1, 1, 0],

[1, 2, 2, 1, 0]]), metric='euclidean', limit=3)

'z': 1,