Module stac_fastapi.elasticsearch.database_logic

Database logic.

Variables

AGGREGATION_MAPPING

COLLECTIONS_INDEX

DEFAULT_SORT

ES_MAX_URL_LENGTH

ITEM_INDICES

MAX_LIMIT

PARENT_ID_SCRIPT

logger

Functions

create_collection_index

def create_collection_index(

) -> None

Create the index for a Collection. The settings of the index template will be used implicitly.

Returns:

Type	Description
None	None

create_index_templates

def create_index_templates(

) -> None

Create index templates for the Collection and Item indices.

Returns:

Type	Description
None	None

delete_item_index

def delete_item_index(
    collection_id: str
)

Delete the index for items in a collection.

Parameters:

Name	Type	Description	Default
collection_id	str	The ID of the collection whose items index will be deleted.	None

Classes

DatabaseLogic

class DatabaseLogic(
    async_settings: stac_fastapi.elasticsearch.config.AsyncElasticsearchSettings = NOTHING,
    sync_settings: stac_fastapi.elasticsearch.config.ElasticsearchSettings = NOTHING,
    item_serializer: Type[stac_fastapi.core.serializers.ItemSerializer] = <class 'stac_fastapi.core.serializers.ItemSerializer'>,
    collection_serializer: Type[stac_fastapi.core.serializers.CollectionSerializer] = <class 'stac_fastapi.core.serializers.CollectionSerializer'>,
    catalog_serializer: Type[stac_fastapi.core.serializers.CatalogSerializer] = <class 'stac_fastapi.core.serializers.CatalogSerializer'>,
    extensions: list[str] = NOTHING
)

Database logic.

Ancestors (in MRO)

• stac_fastapi.core.base_database_logic.BaseDatabaseLogic
• abc.ABC

Class variables

COLLECTION_FIELD

GEOMETRY_FIELD

PROPERTIES_DATETIME_FIELD

PROPERTIES_END_DATETIME_FIELD

PROPERTIES_START_DATETIME_FIELD

aggregation_mapping

client

not_found_error_class

sync_client

Static methods

apply_bbox_filter

def apply_bbox_filter(
    search: elasticsearch.dsl._sync.search.Search,
    bbox: list
)

Filter search results based on bounding box.

Parameters:

Name	Type	Description	Default
search	Search	The search object to apply the filter to.	None
bbox	list	The bounding box coordinates, represented as a list of four values [minx, miny, maxx, maxy].	None

Returns:

Type	Description
None	search (Search): The search object with the bounding box filter applied.

apply_collections_filter

def apply_collections_filter(
    search: elasticsearch.dsl._sync.search.Search,
    collection_ids: list[str]
)

Database logic to search a list of STAC collection ids.

apply_datetime_filter

def apply_datetime_filter(
    search: elasticsearch.dsl._sync.search.Search,
    datetime: str | None
) -> tuple[elasticsearch.dsl._sync.search.Search, dict[str, str | None]]

Apply a filter to search on datetime, start_datetime, and end_datetime fields.

Parameters:

Name	Type	Description	Default
search	None	The search object to filter.	None
datetime	None	str	None

Returns:

Type	Description
None	The filtered search object.

apply_free_text_filter

def apply_free_text_filter(
    search: elasticsearch.dsl._sync.search.Search,
    free_text_queries: list[str] | None
)

Create a free text query for Elasticsearch queries.

This method delegates to the shared implementation in apply_free_text_filter_shared.

Parameters:

Name	Type	Description	Default
search	Search	The search object to apply the query to.	None
free_text_queries	list[str]	None	A list of text strings to search for in the properties.

Returns:

Type	Description
Search	The search object with the free text query applied, or the original search object if no free_text_queries were provided.

apply_ids_filter

def apply_ids_filter(
    search: elasticsearch.dsl._sync.search.Search,
    item_ids: list[str]
)

Database logic to search a list of STAC item ids.

apply_intersects_filter

def apply_intersects_filter(
    search: elasticsearch.dsl._sync.search.Search,
    intersects: stac_fastapi.sfeos_helpers.mappings.Geometry
)

Filter search results based on intersecting geometry.

Parameters:

Name	Type	Description	Default
search	Search	The search object to apply the filter to.	None
intersects	Geometry	The intersecting geometry, represented as a GeoJSON-like object.	None

Returns:

Type	Description
None	search (Search): The search object with the intersecting geometry filter applied.

apply_stacql_filter

def apply_stacql_filter(
    search: elasticsearch.dsl._sync.search.Search,
    op: str,
    field: str,
    value: float
)

Filter search results based on a comparison between a field and a value.

Parameters:

Name	Type	Description	Default
search	Search	The search object to apply the filter to.	None
op	str	The comparison operator to use. Can be 'eq' (equal), 'ne'/'neq' (not equal), 'gt' (greater than), 'gte' (greater than or equal), 'lt' (less than), or 'lte' (less than or equal).	None
field	str	The field to perform the comparison on.	None
value	float	The value to compare the field against.	None

Returns:

Type	Description
None	search (Search): The search object with the specified filter applied.

make_search

def make_search(

)

Database logic to create a Search instance.

populate_sort

def populate_sort(
    sortby: list,
    field_types: dict[str, str] | None = None
) -> dict[str, dict[str, str]] | None

Create a sort configuration for Elasticsearch queries.

This method delegates to the shared implementation in populate_sort_shared.

Parameters:

Name	Type	Description	Default
sortby	list	A list of sort specifications, each containing a field and direction.	None
field_types	dict[str, str]	None	Optional map of sortable field names to their engine field type, used for unmapped_type.

Returns:

Type	Description
None	dict[str, dict[str, str]]

Methods

aggregate

def aggregate(
    self,
    collection_ids: list[str] | None,
    aggregations: list[str],
    search: elasticsearch.dsl._sync.search.Search,
    centroid_geohash_grid_precision: int,
    centroid_geohex_grid_precision: int,
    centroid_geotile_grid_precision: int,
    geometry_geohash_grid_precision: int,
    geometry_geotile_grid_precision: int,
    datetime_frequency_interval: str,
    datetime_search: str,
    ignore_unavailable: bool | None = True
)

Return aggregations of STAC Items.

apply_cql2_filter

def apply_cql2_filter(
    self,
    search: elasticsearch.dsl._sync.search.Search,
    _filter: dict[str, typing.Any] | None
)

Apply a CQL2 filter to an Elasticsearch Search object.

This method transforms a dictionary representing a CQL2 filter into an Elasticsearch query and applies it to the provided Search object. If the filter is None, the original Search object is returned unmodified.

Parameters:

Name	Type	Description	Default
search	Search	The Elasticsearch Search object to which the filter will be applied.	None
_filter	dict[str, Any]	None	The filter in dictionary form that needs to be applied to the search. The dictionary should follow the structure required by the to_es function which converts it to an Elasticsearch query.

Returns:

Type	Description
Search	The modified Search object with the filter applied if a filter is provided, otherwise the original Search object.

async_prep_create_item

def async_prep_create_item(
    self,
    item: stac_fastapi.types.stac.Item,
    base_url: str
) -> stac_fastapi.types.stac.Item

Preps an item for insertion into the database.

Parameters:

Name	Type	Description	Default
item	Item	The item to be prepped for insertion.	None
base_url	str	The base URL used to create the item's self URL.	None

Returns:

Type	Description
Item	The prepped item.

bulk_async

def bulk_async(
    self,
    collection_id: str,
    processed_items: list[stac_fastapi.types.stac.Item],
    op_type: str = 'create',
    **kwargs: Any
) -> tuple[int, list[dict[str, typing.Any]]]

Perform a bulk insert of items into the database asynchronously.

Parameters:

Name	Type	Description	Default
collection_id	str	The ID of the collection to which the items belong.	None
processed_items	list[Item]	A list of Item objects to be inserted into the database.	None
op_type	str	The operation type for the bulk actions. "create" for insert-only (rejects duplicates at ES/OS level), "index" for upsert. Defaults to "create".	None
**kwargs	Any	Additional keyword arguments, including: - refresh (str, optional): Whether to refresh the index after the bulk insert. Can be "true", "false", or "wait_for". Defaults to the value of self.sync_settings.database_refresh. - refresh (bool, optional): Whether to refresh the index after the bulk insert. - raise_on_error (bool, optional): Whether to raise an error if any of the bulk operations fail. Defaults to the value of self.async_settings.raise_on_bulk_error.	None

Returns:

Type	Description
tuple[int, list[dict[str, Any]]]	A tuple containing: - The number of successfully processed actions (success). - A list of errors encountered during the bulk operation (errors).

bulk_async_prep_create_item

def bulk_async_prep_create_item(
    self,
    item: stac_fastapi.types.stac.Item,
    base_url: str
) -> stac_fastapi.types.stac.Item

Validate and serialize an item for bulk indexing.

This method performs pre-insertion validation and serialization: - Verifying that the collection the item belongs to exists. - Serializing the item into a database-compatible format.

Note: Duplicate item detection is not performed here. It is handled atomically by the database engine via op_type="create" during the bulk indexing phase.

Parameters:

Name	Type	Description	Default
item	Item	The item to be prepared for insertion.	None
base_url	str	The base URL used to construct the item's self URL.	None

Returns:

Type	Description
Item	The prepared item, serialized into a database-compatible format.

Raises:

Type	Description
NotFoundError	If the collection that the item belongs to does not exist in the database.

bulk_sync

def bulk_sync(
    self,
    collection_id: str,
    processed_items: list[stac_fastapi.types.stac.Item],
    op_type: str = 'create',
    **kwargs: Any
) -> tuple[int, list[dict[str, typing.Any]]]

Perform a bulk insert of items into the database synchronously.

Parameters:

Name	Type	Description	Default
collection_id	str	The ID of the collection to which the items belong.	None
processed_items	list[Item]	A list of Item objects to be inserted into the database.	None
op_type	str	The operation type for the bulk actions. "create" for insert-only (rejects duplicates at ES/OS level), "index" for upsert. Defaults to "create".	None
**kwargs	Any	Additional keyword arguments, including: - refresh (str, optional): Whether to refresh the index after the bulk insert. Can be "true", "false", or "wait_for". Defaults to the value of self.sync_settings.database_refresh. - refresh (bool, optional): Whether to refresh the index after the bulk insert. - raise_on_error (bool, optional): Whether to raise an error if any of the bulk operations fail. Defaults to the value of self.sync_settings.raise_on_bulk_error.	None

Returns:

Type	Description
tuple[int, list[dict[str, Any]]]	A tuple containing: - The number of successfully processed actions (success). - A list of errors encountered during the bulk operation (errors).

bulk_sync_prep_create_item

def bulk_sync_prep_create_item(
    self,
    item: stac_fastapi.types.stac.Item,
    base_url: str
) -> stac_fastapi.types.stac.Item

Validate and serialize an item for bulk indexing.

This method performs pre-insertion validation and serialization: - Verifying that the collection the item belongs to exists. - Serializing the item into a database-compatible format.

Note: Duplicate item detection is not performed here. It is handled atomically by the database engine via op_type="create" during the bulk indexing phase.

Parameters:

Name	Type	Description	Default
item	Item	The item to be prepared for insertion.	None
base_url	str	The base URL used to construct the item's self URL.	None

Returns:

Type	Description
Item	The prepared item, serialized into a database-compatible format.

Raises:

Type	Description
NotFoundError	If the collection that the item belongs to does not exist in the database.

check_collection_exists

def check_collection_exists(
    self,
    collection_id: str
)

Database logic to check if a collection exists.

check_collection_exists_sync

def check_collection_exists_sync(
    self,
    collection_id: str
)

Database logic to check if a collection exists, using the sync client.

create_catalog

def create_catalog(
    self,
    catalog: dict,
    refresh: bool = False
) -> stac_fastapi.core.etag.DocumentVersion

Create a catalog in Elasticsearch.

Parameters:

Name	Type	Description	Default
catalog	dict	The catalog document to create.	None
refresh	bool	Whether to refresh the index after creation.	None

Returns:

Type	Description
DocumentVersion	The version of the stored document.

Raises:

Type	Description
ConflictError	If any document (Catalog or Collection) already exists with the same id.

create_catalog_catalog

def create_catalog_catalog(
    self,
    catalog_id: str,
    catalog: Any,
    request: Any
) -> Any

Create a sub-catalog within a catalog.

Parameters:

Name	Type	Description	Default
catalog_id	str	The ID of the parent catalog.	None
catalog	Any	The catalog object to create.	None
request	Any	The request object.	None

Returns:

Type	Description
None	The created catalog.

Raises:

Type	Description
NotFoundError	If the parent catalog does not exist.

create_catalog_collection

def create_catalog_collection(
    self,
    catalog_id: str,
    collection: Any,
    request: Any
) -> Any

Create a collection within a catalog.

Parameters:

Name	Type	Description	Default
catalog_id	str	The ID of the parent catalog.	None
collection	Any	The collection object to create.	None
request	Any	The request object.	None

Returns:

Type	Description
None	The created collection.

Raises:

Type	Description
NotFoundError	If the parent catalog does not exist.

create_collection

def create_collection(
    self,
    collection: stac_fastapi.types.stac.Collection,
    **kwargs: Any
) -> stac_fastapi.core.etag.DocumentVersion

Create a single collection in the database.

Parameters:

Name	Type	Description	Default
collection	Collection	The Collection object to be created.	None
**kwargs	None	Additional keyword arguments. - refresh (str): Whether to refresh the index after the operation. Can be "true", "false", or "wait_for". - refresh (bool): Whether to refresh the index after the operation. Defaults to the value in self.async_settings.database_refresh.	None

Returns:

Type	Description
None	None

Raises:

Type	Description
ConflictError	If a Collection with the same id already exists in the database.

create_item

def create_item(
    self,
    item: stac_fastapi.types.stac.Item,
    base_url: str = '',
    upsert: bool = False,
    existing_hit: dict | None = None,
    version: stac_fastapi.core.etag.DocumentVersion | None = None,
    **kwargs: Any
) -> stac_fastapi.core.etag.DocumentVersion

Database logic for creating one item.

Parameters:

Name	Type	Description	Default
item	Item	The item to be created.	None
base_url	str	The base URL for the item. Defaults to an empty string.	an empty string
upsert	bool	If False (default), performs an insert-only operation that rejects duplicates (op_type="create"). If True, performs an upsert that overwrites existing items (op_type="index").	None
existing_hit	dict	A write-lookup hit already fetched via get_item_hit_for_write. When given, the existing-document check reuses it instead of querying the alias again.	None
version	DocumentVersion	Only overwrite this stored version of the item (If-Match).	None
**kwargs	None	Additional keyword arguments. - refresh (str): Whether to refresh the index after the operation. Can be "true", "false", or "wait_for". - refresh (bool): Whether to refresh the index after the operation. Defaults to the value in self.async_settings.database_refresh.	None

Returns:

Type	Description
DocumentVersion	The version this write stored.

Raises:

Type	Description
ItemAlreadyExistsError	If the item already exists and upsert is False.
HTTPException	412 if version is no longer the stored version.

delete_catalog

def delete_catalog(
    self,
    catalog_id: str,
    refresh: bool = False,
    version: stac_fastapi.core.etag.DocumentVersion | None = None
) -> None

Delete a catalog from Elasticsearch.

With version (If-Match), the catalog is deleted only while that version is stored, and before its children are unlinked, so a refused delete (412) changes nothing.

Parameters:

Name	Type	Description	Default
catalog_id	str	The ID of the catalog to delete.	None
refresh	bool	Whether to refresh the index after deletion.	None
version	DocumentVersion	Only delete this stored version of the catalog (If-Match); 412 otherwise.	None

Raises:

Type	Description
NotFoundError	If the document does not exist or is not a Catalog (e.g. a Collection sharing the same index). Deleting a catalog must never remove Collection or Item data.

delete_collection

def delete_collection(
    self,
    collection_id: str,
    version: stac_fastapi.core.etag.DocumentVersion | None = None,
    **kwargs: Any
)

Delete a collection from the database.

Parameters:

Name	Type	Description	Default
collection_id	str	The ID of the collection to be deleted.	None
version	DocumentVersion	Only delete this stored version of the collection (If-Match); 412 otherwise.	None
kwargs	Any	Additional keyword arguments, including refresh. - refresh (str): Whether to refresh the index after the operation. Can be "true", "false", or "wait_for". - refresh (bool): Whether to refresh the index after the operation. Defaults to the value in self.async_settings.database_refresh.	None

Returns:

Type	Description
None	None

Raises:

Type	Description
NotFoundError	If the collection with the given collection_id is not found in the database.

delete_collections

def delete_collections(
    self
) -> None

Danger. this is only for tests.

delete_item

def delete_item(
    self,
    item_id: str,
    collection_id: str,
    version: stac_fastapi.core.etag.DocumentVersion | None = None,
    **kwargs: Any
)

Delete a single item from the database.

Parameters:

Name	Type	Description	Default
item_id	str	The id of the Item to be deleted.	None
collection_id	str	The id of the Collection that the Item belongs to.	None
version	DocumentVersion	Only delete this stored version of the item (If-Match); 412 otherwise.	None
**kwargs	None	Additional keyword arguments. - refresh (str): Whether to refresh the index after the operation. Can be "true", "false", or "wait_for". - refresh (bool): Whether to refresh the index after the operation. Defaults to the value in self.async_settings.database_refresh.	None

Returns:

Type	Description
None	None

Raises:

Type	Description
NotFoundError	If the Item does not exist in the database.

delete_items

def delete_items(
    self
) -> None

Danger. this is only for tests.

execute_search

def execute_search(
    self,
    search: elasticsearch.dsl._sync.search.Search,
    limit: int,
    token: str | None,
    sort: dict[str, dict[str, str]] | None,
    collection_ids: list[str] | None,
    datetime_search: str,
    cql2_metadata: dict[str, typing.Any] | None = None,
    ignore_unavailable: bool = True
) -> tuple[typing.Iterable[dict[str, typing.Any]], int | None, str | None]

Execute a search query with limit and other optional parameters.

Parameters:

Name	Type	Description	Default
search	Search	The search query to be executed.	None
limit	int	The maximum number of results to be returned.	None
token	str	None	The token used to return the next set of results.
sort	dict[str, dict[str, str]]	None	Specifies how the results should be sorted.
collection_ids	list[str]	None	The collection ids to search.
datetime_search	str	Datetime used for index selection.	None
ignore_unavailable	bool	Whether to ignore unavailable collections. Defaults to True.	True

Returns:

Type	Description
tuple[Iterable[dict[str, Any]], int	None, str

Raises:

Type	Description
NotFoundError	If the collections specified in collection_ids do not exist.

find_catalog

def find_catalog(
    self,
    catalog_id: str
) -> dict

Find a catalog in Elasticsearch by ID.

Parameters:

Name	Type	Description	Default
catalog_id	str	The ID of the catalog to find.	None

Returns:

Type	Description
dict	The catalog document.

Raises:

Type	Description
NotFoundError	If the catalog is not found.

find_catalog_with_version

def find_catalog_with_version(
    self,
    catalog_id: str
) -> tuple[dict, stac_fastapi.core.etag.DocumentVersion]

Find a catalog and the version of its stored document.

Parameters:

Name	Type	Description	Default
catalog_id	str	The ID of the catalog to find.	None

Returns:

Type	Description
None	The catalog document, and its stored version.

Raises:

Type	Description
NotFoundError	If the catalog is not found.

find_collection

def find_collection(
    self,
    collection_id: str
) -> stac_fastapi.types.stac.Collection

Find and return a collection from the database.

Parameters:

Name	Type	Description	Default
self	None	The instance of the object calling this function.	None
collection_id	str	The ID of the collection to be found.	None

Returns:

Type	Description
Collection	The found collection, represented as a Collection object.

Raises:

Type	Description
NotFoundError	If the collection with the given collection_id is not found in the database.

find_collection_with_version

def find_collection_with_version(
    self,
    collection_id: str
) -> tuple[stac_fastapi.types.stac.Collection, stac_fastapi.core.etag.DocumentVersion]

Find a collection and the version of its stored document.

Parameters:

Name	Type	Description	Default
collection_id	str	The ID of the collection to be found.	None

Returns:

Type	Description
None	The collection, and its stored version.

Raises:

Type	Description
NotFoundError	If the collection with the given collection_id is not found in the database.

get_all_catalogs

def get_all_catalogs(
    self,
    token: str | None,
    limit: int,
    request: Any = None,
    sort: list[dict[str, typing.Any]] | None = None,
    filter: dict[str, typing.Any] | None = None
) -> tuple[list[dict[str, typing.Any]], str | None, int | None]

Retrieve a list of catalogs from Elasticsearch, supporting pagination.

Parameters:

Name	Type	Description	Default
token	str	None	The pagination token.
limit	int	The number of results to return.	None
request	Any	The FastAPI request object. Defaults to None.	None
sort	list[dict[str, Any]]	None	Optional sort parameter. Defaults to None.
filter	dict[str, Any]	None	A CQL2 JSON filter the catalogs must match. Defaults to None.

Returns:

Type	Description
None	A tuple of (catalogs, next pagination token if any, optional count).

get_all_collection_queryables

def get_all_collection_queryables(
    self
) -> list[dict]

Retrieve all queryables from all collections safely.

Generates queryables on-the-fly from each collection's item index mappings using a scroll to prevent memory spikes, and a semaphore to prevent connection pool exhaustion.

Returns:

Type	Description
None	A list of queryables dictionaries, one from each active collection.

get_all_collections

def get_all_collections(
    self,
    token: str | None,
    limit: int,
    request: starlette.requests.Request,
    sort: list[dict[str, typing.Any]] | None = None,
    bbox: list[float] | None = None,
    q: list[str] | None = None,
    filter: dict[str, typing.Any] | None = None,
    query: dict[str, dict[str, typing.Any]] | None = None,
    datetime: str | None = None
) -> tuple[list[dict[str, typing.Any]], str | None, int | None]

Retrieve a list of collections from Elasticsearch, supporting pagination.

Parameters:

Name	Type	Description	Default
token	str	None	The pagination token.
limit	int	The number of results to return.	None
request	Request	The FastAPI request object.	None
sort	list[dict[str, Any]]	None	Optional sort parameter from the request.
bbox	list[float]	None	Bounding box to filter collections by spatial extent.
q	list[str]	None	Free text search terms.
query	dict[str, dict[str, Any]]	None	Query extension parameters.
filter	dict[str, Any]	None	Structured query in CQL2 format.
datetime	str	None	Temporal filter.

Returns:

Type	Description
None	A tuple of (collections, next pagination token if any).

get_catalog

def get_catalog(
    self,
    catalog_id: str,
    request: Any,
    settings: dict,
    limit: int = 100
) -> Any

Get a specific catalog.

get_catalog_catalogs

def get_catalog_catalogs(
    self,
    catalog_id: str,
    limit: int,
    token: str | None,
    request: Any = None,
    filter: dict[str, typing.Any] | None = None
) -> tuple[list[dict[str, typing.Any]], int | None, str | None]

Get sub-catalogs within a catalog.

Parameters:

Name	Type	Description	Default
catalog_id	str	The ID of the parent catalog.	None
limit	int	Number of results to return.	None
token	str	None	Pagination token.
request	Any	The request object.	None
filter	dict[str, Any]	None	A CQL2 JSON filter the results must match.

Returns:

Type	Description
None	Tuple containing list of sub-catalogs, next token, and total count.

get_catalog_children

def get_catalog_children(
    self,
    catalog_id: str,
    limit: int,
    token: str | None,
    request: Any = None,
    resource_type: str | None = None,
    filter: dict[str, typing.Any] | None = None
) -> tuple[list[dict[str, typing.Any]], int | None, str | None]

Get children of a catalog (both sub-catalogs and collections).

Parameters:

Name	Type	Description	Default
catalog_id	str	The ID of the parent catalog.	None
limit	int	Number of results to return.	None
token	str	None	Pagination token.
request	Any	The request object.	None
resource_type	str	None	Type of resource to filter by (e.g. "Collection", "Catalog").
filter	dict[str, Any]	None	A CQL2 JSON filter the results must match.

Returns:

Type	Description
None	Tuple containing list of children, next token, and total count.

get_catalog_collection

def get_catalog_collection(
    self,
    catalog_id: str,
    collection_id: str,
    request: Any
) -> Any

Get a specific collection within a catalog.

Validation is now handled securely by CatalogsClient. Just return the collection.

get_catalog_collection_items

def get_catalog_collection_items(
    self,
    catalog_id: str,
    collection_id: str,
    request: Any,
    bbox: list[float] | None = None,
    datetime: str | None = None,
    limit: int = 10,
    sortby: str | None = None,
    filter: dict[str, typing.Any] | None = None,
    token: str | None = None,
    query: str | None = None,
    fields: list[str] | None = None
) -> Any

Get items for a collection within a catalog.

Hierarchy validation is already performed by CatalogsClient. Skip the redundant DB checks and go straight to the search.

get_catalog_collections

def get_catalog_collections(
    self,
    catalog_id: str,
    limit: int,
    token: str | None,
    request: Any = None,
    filter: dict[str, typing.Any] | None = None,
    sort: list[dict[str, typing.Any]] | None = None,
    q: list[str] | None = None
) -> tuple[list[dict[str, typing.Any]], int | None, str | None]

Get collections within a catalog.

Parameters:

Name	Type	Description	Default
catalog_id	str	The ID of the parent catalog.	None
limit	int	Number of results to return.	None
token	str	None	Pagination token.
request	Any	The request object.	None
filter	dict[str, Any]	None	A CQL2 JSON filter the results must match.
sort	list[dict[str, Any]]	None	Field/direction pairs from sortby.
q	list[str]	None	Free text search terms.

Returns:

Type	Description
None	Tuple containing list of collections, next token, and total count.

get_collections_queryables_mapping

def get_collections_queryables_mapping(
    self
) -> dict

Retrieve mapping of Queryables for collection search.

Used when translating CQL2 filters applied to collection search so that field paths are resolved against the collections index rather than the items index.

Returns:

Type	Description
dict	A dictionary containing the Collection Queryables mappings.

get_item_for_write

def get_item_for_write(
    self,
    collection_id: str,
    item_id: str
) -> dict

Retrieve an item for a write without applying read visibility filters.

Under datetime index filtering the real-time mget lookup is used for the same reason as in :meth:get_item_hit_for_write.

get_item_hit_for_write

def get_item_hit_for_write(
    self,
    collection_id: str,
    item_id: str
) -> dict

Retrieve the write-lookup hit for an item, including its version.

Returns a hit dict carrying _source, _index, _seq_no and _primary_term, so callers that then write via create_item can pass the result back as existing_hit (the existence check is not repeated) or read the stored version from it.

Under datetime index filtering, _id uniqueness is enforced per physical index and a just-written document may not be visible to _search yet, so the lookup is a real-time mget over the collection alias's concrete indexes instead.

Raises:

Type	Description
NotFoundError	If the item does not exist in the collection.

get_items_mapping

def get_items_mapping(
    self,
    collection_id: str
) -> dict[str, typing.Any]

Get the mapping for the specified collection's items index.

Parameters:

Name	Type	Description	Default
collection_id	str	The ID of the collection to get items mapping for.	None

Returns:

Type	Description
dict[str, Any]	The mapping information.

get_items_unique_values

def get_items_unique_values(
    self,
    collection_id: str,
    field_names: Iterable[str],
    *,
    limit: int = 100
) -> dict[str, list[str]]

Get the unique values for the given fields in the collection.

get_one_item

def get_one_item(
    self,
    collection_id: str,
    item_id: str,
    *,
    include_hidden: bool = False
) -> dict

Retrieve a single item from the database.

Parameters:

Name	Type	Description	Default
collection_id	str	The id of the Collection that the Item belongs to.	None
item_id	str	The id of the Item.	None

Returns:

Type	Description
None	item (dict): A dictionary containing the source data for the Item.

Raises:

Type	Description
NotFoundError	If the specified Item does not exist in the Collection.

get_one_item_with_version

def get_one_item_with_version(
    self,
    collection_id: str,
    item_id: str,
    *,
    include_hidden: bool = False
) -> tuple[dict, stac_fastapi.core.etag.DocumentVersion]

Retrieve a single item and the version of its stored document.

Parameters:

Name	Type	Description	Default
collection_id	str	The id of the Collection that the Item belongs to.	None
item_id	str	The id of the Item.	None
include_hidden	bool	Return the item even if HIDE_ITEM_PATH hides it, as a write needs the stored document.	None

Returns:

Type	Description
None	The source data for the Item, and its stored version.

Raises:

Type	Description
NotFoundError	If the specified Item does not exist in the Collection.

get_queryables_mapping

def get_queryables_mapping(
    self,
    collection_id: str = '*'
) -> dict

Retrieve mapping of Queryables for search.

Args: collection_id (str, optional): The id of the Collection the Queryables belongs to. Defaults to "*".

Returns: dict: A dictionary containing the Queryables mappings.

json_patch_collection

def json_patch_collection(
    self,
    collection_id: str,
    operations: list[stac_fastapi.extensions.transaction.request.PatchAddReplaceTest | stac_fastapi.extensions.transaction.request.PatchMoveCopy | stac_fastapi.extensions.transaction.request.PatchRemove],
    base_url: str,
    create_nest: bool = False,
    refresh: bool = True,
    version: stac_fastapi.core.etag.DocumentVersion | None = None
) -> stac_fastapi.types.stac.Collection

Database logic for json patching a collection following RF6902.

Parameters:

Name	Type	Description	Default
collection_id	str	Id of collection to be patched.	None
operations	list	list of operations to run.	None
base_url	str	The base URL used for constructing links.	None
refresh	bool	Refresh the index after performing the operation. Defaults to True.	True

Returns:

Type	Description
None	patched collection.

json_patch_item

def json_patch_item(
    self,
    collection_id: str,
    item_id: str,
    operations: list[stac_fastapi.extensions.transaction.request.PatchAddReplaceTest | stac_fastapi.extensions.transaction.request.PatchMoveCopy | stac_fastapi.extensions.transaction.request.PatchRemove],
    base_url: str,
    create_nest: bool = False,
    refresh: bool = True,
    version: stac_fastapi.core.etag.DocumentVersion | None = None
) -> stac_fastapi.types.stac.Item

Database logic for json patching an item following RF6902.

Parameters:

Name	Type	Description	Default
collection_id	str	Collection that item belongs to.	None
item_id	str	Id of item to be patched.	None
operations	list	list of operations to run.	None
base_url	str	The base URL used for constructing URLs for the item.	None
refresh	bool	Refresh the index after performing the operation. Defaults to True.	True

Returns:

Type	Description
None	patched item.

merge_patch_collection

def merge_patch_collection(
    self,
    collection_id: str,
    collection: stac_fastapi.extensions.transaction.request.PartialCollection,
    base_url: str,
    refresh: bool = True,
    version: stac_fastapi.core.etag.DocumentVersion | None = None
) -> stac_fastapi.types.stac.Collection

Database logic for merge patching a collection following RF7396.

Parameters:

Name	Type	Description	Default
collection_id	str	Id of collection to be patched.	None
collection	PartialCollection	The partial collection to be updated.	None
base_url	None	(str): The base URL used for constructing links.	None
refresh	bool	Refresh the index after performing the operation. Defaults to True.	True

Returns:

Type	Description
None	patched collection.

merge_patch_item

def merge_patch_item(
    self,
    collection_id: str,
    item_id: str,
    item: stac_fastapi.extensions.transaction.request.PartialItem,
    base_url: str,
    refresh: bool = True,
    version: stac_fastapi.core.etag.DocumentVersion | None = None
) -> stac_fastapi.types.stac.Item

Database logic for merge patching an item following RF7396.

Parameters:

Name	Type	Description	Default
collection_id	str	Collection that item belongs to.	None
item_id	str	Id of item to be patched.	None
item	PartialItem	The partial item to be updated.	None
base_url	None	(str): The base URL used for constructing URLs for the item.	None
refresh	bool	Refresh the index after performing the operation. Defaults to True.	True

Returns:

Type	Description
None	patched item.

unlink_catalog_orphans

def unlink_catalog_orphans(
    self,
    catalog_id: str
) -> None

Unlink children that still reference a catalog that no longer exists.

A delete that failed after it removed the catalog leaves them linked; a retry calls this. Nothing is deleted: the id must name no document at all, and a child must still reference it.

update_catalog

def update_catalog(
    self,
    catalog_id: str,
    catalog: dict,
    refresh: bool | str = False,
    version: stac_fastapi.core.etag.DocumentVersion | None = None
) -> stac_fastapi.core.etag.DocumentVersion

Replace a catalog, keeping its stored parent_ids.

parent_ids is backend-owned: the write is conditional on the version read and retried, so a concurrent link or unlink is not lost. With version (If-Match), only that stored version is replaced: the write is conditional on it and is not retried.

Returns:

Type	Description
DocumentVersion	The version of the stored document.

Raises:

Type	Description
NotFoundError	If the catalog does not exist.
ConflictError	If concurrent writes exhaust the retries.
HTTPException	412 if version is no longer the stored version.

update_collection

def update_collection(
    self,
    collection_id: str,
    collection: stac_fastapi.types.stac.Collection,
    preserve_parent_ids: bool = False,
    version: stac_fastapi.core.etag.DocumentVersion | None = None,
    **kwargs: Any
) -> stac_fastapi.core.etag.DocumentVersion | None

Update a collection in the database.

Parameters:

Name	Type	Description	Default
collection_id	str	The ID of the collection to be updated.	None
collection	Collection	The Collection object to be used for the update.	None
preserve_parent_ids	bool	Keep the stored catalog memberships (parent_ids) instead of taking them from collection. The write is conditional on the version read, retried on conflict.	None
version	DocumentVersion	Only replace this stored version of the collection (If-Match); 412 otherwise, without retrying.	None
**kwargs	None	Additional keyword arguments. - refresh (str): Whether to refresh the index after the operation. Can be "true", "false", or "wait_for". - refresh (bool): Whether to refresh the index after the operation. Defaults to the value in self.async_settings.database_refresh.	None

Returns:

Type	Description
None	None

Raises:

Type	Description
NotFoundError	If the collection with the given collection_id is not found in the database.
ConflictError	If a conflict occurs during the update.

update_parent_ids

def update_parent_ids(
    self,
    doc_id: str,
    doc_type: str,
    parent_id: str,
    add: bool,
    refresh: bool | str = False
) -> dict

Atomically add or remove one parent id in a document's parent_ids.

Parameters:

Name	Type	Description	Default
doc_id	None	The id of the Collection or Catalog to update.	None
doc_type	None	"Collection" or "Catalog"; the stored type must match.	None
parent_id	None	The parent catalog id to add or remove.	None
add	None	Add parent_id if True, remove it if False.	None
refresh	None	Whether to refresh the index after the update.	None

Raises:

Type	Description
NotFoundError	If no doc_type document with this id exists.
ConflictError	If concurrent writes exhaust the update's retries.