Search features

async AsyncCogniteClient.geospatial.search_features( feature_type_external_id: str, filter: dict[str, Any] | None = None, properties: dict[str, Any] | None = None, limit: int = 25, order_by: Sequence[OrderSpec] | None = None, allow_crs_transformation: bool = False, allow_dimensionality_mismatch: bool = False, ) → FeatureList

Search for features.

This method allows to order the result by one or more of the properties of the feature type. However, the number of items returned is limited to 1000 and there is no support for cursors yet. If you need to return more than 1000 items, use the stream_features(…) method instead.

Parameters:

feature_type_external_id (str) – The feature type to search for
filter (dict[str, Any] | None) – The search filter
properties (dict[str, Any] | None) – The output property selection
limit (int) – Maximum number of results
order_by (Sequence[OrderSpec] | None) – The order specification
allow_crs_transformation (bool) – If true, then input geometries will be transformed into the Coordinate Reference System defined in the feature type specification. When it is false, then requests with geometries in Coordinate Reference System different from the ones defined in the feature type will result in CogniteAPIError exception.
allow_dimensionality_mismatch (bool) – Indicating if the spatial filter operators allow input geometries with a different dimensionality than the properties they are applied to. Defaults to False.

Returns:

the filtered features

Return type:

FeatureList

Examples

Search for features:

>>> from cognite.client import CogniteClient, AsyncCogniteClient
>>> client = CogniteClient()
>>> # async_client = AsyncCogniteClient()  # another option
>>> my_feature_type = client.geospatial.retrieve_feature_types(
...     external_id="my_feature_type"
... )
>>> my_feature = client.geospatial.create_features(
...     feature_type_external_id=my_feature_type,
...     feature=Feature(
...         external_id="my_feature", temperature=12.4, location={"wkt": "POINT(0 1)"}
...     ),
... )
>>> res = client.geospatial.search_features(
...     feature_type_external_id="my_feature_type",
...     filter={"range": {"property": "temperature", "gt": 12.0}},
... )
>>> for f in res:
...     # do something with the features

Search for features and select output properties:

>>> res = client.geospatial.search_features(
...     feature_type_external_id=my_feature_type,
...     filter={},
...     properties={"temperature": {}, "pressure": {}},
... )

Search for features and do CRS conversion on an output property:

>>> res = client.geospatial.search_features(
...     feature_type_external_id=my_feature_type,
...     filter={},
...     properties={"location": {"srid": 3995}},
... )

Search for features and order results:

>>> res = client.geospatial.search_features(
...     feature_type_external_id=my_feature_type,
...     filter={},
...     order_by=[OrderSpec("temperature", "ASC"), OrderSpec("pressure", "DESC")],
... )

Search for features with spatial filters:

>>> res = client.geospatial.search_features(
...     feature_type_external_id=my_feature_type,
...     filter={
...         "stWithin": {
...             "property": "location",
...             "value": {"wkt": "POLYGON((0 0, 0 1, 1 1, 0 0))"},
...         }
...     },
... )

Combining multiple filters:

>>> res = client.geospatial.search_features(
...     feature_type_external_id=my_feature_type,
...     filter={
...         "and": [
...             {"range": {"property": "temperature", "gt": 12.0}},
...             {
...                 "stWithin": {
...                     "property": "location",
...                     "value": {"wkt": "POLYGON((0 0, 0 1, 1 1, 0 0))"},
...                 }
...             },
...         ]
...     },
... )

>>> res = client.geospatial.search_features(
...     feature_type_external_id=my_feature_type,
...     filter={
...         "or": [
...             {"range": {"property": "temperature", "gt": 12.0}},
...             {
...                 "stWithin": {
...                     "property": "location",
...                     "value": {"wkt": "POLYGON((0 0, 0 1, 1 1, 0 0))"},
...                 }
...             },
...         ]
...     },
... )