.. _querying-data: 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 `_. .. _choose-a-class-and-return-properties: 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: .. code-block:: json [{"AddEntity": { "class": "Person", "properties": {"name": "Ada", "age": 36, "city": "London"} }}] Each execution creates a new object. A unique application identifier combined with :doc:`parameters/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: .. code-block:: json [{"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 :doc:`ReadingResults` for omitted results, counts, and binary payloads. .. _combine-conditions: Combining conditions ----------------------- An ``all`` expression matches when every condition holds. This query selects adults whose city is London: .. code-block:: json [{"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; :doc:`HandlingOfMissingData` 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"``. .. _continue-the-query: Related query features ------------------------- :doc:`TransactionsAndReferences` explains how commands select connected objects within a request. :doc:`ReadingResults` covers ordering and pagination. The :doc:`parameters/constraints` reference lists operators and functions; :doc:`examples/QuerySemantics` explains precision, type errors, text normalization, and index coverage. Indexes can improve performance, but they do not replace the filter's correctness rules.