Skip to main content

Querying data

A query selects objects and specifies the information to return. In a FindEntity command, with_class identifies the class, constraints filters its objects, and results selects the output properties. The same constraint expressions apply to images, videos, and other object types.

The examples below use an established client connection. Connection setup is covered in the Quick Start.

Classes, filters, and returned properties​

The following examples assume a Person class containing people with name, numeric age, and city properties. For example, an application with permission to add entities can create a person with this complete request:

[{"AddEntity": {
    "class": "Person",
    "properties": {"name": "Ada", "age": 36, "city": "London"}
}}]

Each execution creates a new object. A unique application identifier combined with if_not_found allows a conditional add to detect an existing object.

The following query selects people aged 18 or over and returns their names and ages:

[{"FindEntity": {
    "with_class": "Person",
    "constraints": ["$age", ">=", 18],
    "results": {"list": ["name", "age"]}
}}]

$age refers to the property’s value. >= compares it with the number 18. results.list requests the properties to return; it does not select which objects match. If Ada is the only person in the class, the response contains one entity with name: "Ada" and age: 36. See Reading results for omitted results, counts, and binary payloads.

Combining conditions​

An all expression matches when every condition holds. This query selects adults whose city is London:

[{"FindEntity": {
    "with_class": "Person",
    "constraints": ["all",
        ["$age", ">=", 18],
        ["$city", "==", "London"]
    ],
    "results": {"list": ["name"]}
}}]

An any expression matches when at least one condition holds. not negates a single condition, as in ["not", ["$city", "==", "London"]]. A missing property can satisfy a negated or unequal comparison; Handling of Missing Data explains these cases.

Comparisons distinguish value types: 18 is a number, while "18" is a string. An extra dollar sign distinguishes a literal from a property reference: "$$USD" represents the string "$USD".

Transactions and references explains how commands select connected objects within a request. Reading results covers ordering and pagination. The constraints reference lists operators and functions; Query semantics and limitations explains precision, type errors, text normalization, and index coverage. Indexes can improve performance, but they do not replace the filter’s correctness rules.