Search and record sets¶

Contains semantics¶

Catalog.search(contains=...) keeps the comparison rules simple and type-directed:

strings use substring containment;
lists and other stored sequences use membership matching, and a list expected value requires every expected item to be present;
mappings match an expected mapping as a subset of key/value pairs;
scalar values fall back to equality.

Search filter arguments such as where, contains, regex, and match must be mappings from field name to expected value. exists and missing must be sequences of field names, not bare strings.

class ogcat.SearchQuery(terms=(), *, criteria=None)[source]¶

Bases: object

Backend-neutral catalog record search query.

Terms are combined with AND semantics.

Parameters:

terms (Sequence[SearchTerm]) – Search terms to require.
criteria (Sequence[SearchTerm] | None) – Backwards-compatible alias for terms.

terms: tuple[SearchTerm, ...]¶

property criteria: tuple[SearchTerm, ...]¶: Backwards-compatible alias for search terms.

classmethod all()[source]¶

Return a query that matches every record.

Return type:: SearchQuery

eq(value: Any = None) → SearchQuery¶

Return type:: SearchQuery

equals(value: Any = None) → SearchQuery¶

Return type:: SearchQuery

contains(value: Any = None) → SearchQuery¶

Return type:: SearchQuery

match(value: Any = None) → SearchQuery¶

Return type:: SearchQuery

matches(value: Any = None) → SearchQuery¶

Return type:: SearchQuery

regex(value: Any = None) → SearchQuery¶

Return type:: SearchQuery

exists(value: Any = None) → SearchQuery¶

Return type:: SearchQuery

missing(value: Any = None) → SearchQuery¶

Return type:: SearchQuery

classmethod where(filters=None, **kwargs)[source]¶

Build an equality query from keyword filters.

Return type:: SearchQuery

classmethod from_filters(*, where=None, contains=None, regex=None, match=None, exists=None, missing=None)[source]¶

Build a query from simple filter mappings.

Return type:: SearchQuery

and_(*queries)[source]¶

Return a query requiring this query and all provided queries to match.

Return type:: SearchQuery

class ogcat.SearchTerm(field, op, value=None)[source]¶

Bases: object

One backend-neutral search predicate.

Parameters:

field (FieldPath) – Field path to resolve.
op (SearchOp) – Search operator.
value (Any) – Optional comparison value.

field: FieldPath¶

op: SearchOp¶

value: Any¶

classmethod build(field, op, value=None)[source]¶

Build a search term from user-facing field and operator inputs.

Return type:: SearchTerm

class ogcat.FieldPath(raw)[source]¶

Bases: object

Backend-neutral field path used by search terms.

Parameters:: raw (str) – User-facing field path. user. and derived. prefixes are normalised to stored metadata namespaces.

raw: str¶

property stored: str¶: Return this field path normalised to the stored record shape.

class ogcat.CatalogRecordSet(records, *, resolution_order=None, schema_display_fields=None, default_display_fields=None)[source]¶

Bases: Sequence[CatalogRecord]

A lightweight, sequence-like view of catalog records.

Parameters:

records (Sequence[CatalogRecord]) – Records to expose.
resolution_order (Sequence[str] | None) – Namespace order for flattened field lookup.

property ids: list[str]¶: Return stable string IDs for records in this set.

select(*fields)[source]¶

Return JSON-friendly rows for the selected fields.

Return type:: list[MetadataDict]

rows(fields='default')[source]¶

Return JSON-friendly rows for the selected fields.

Parameters:: fields (Sequence[str] | str) – Field names or dotted paths to resolve.
Return type:: list[MetadataDict]
Returns:: One dictionary per record.

display_rows(fields='default', *, limit=None)[source]¶

Return CLI-style display rows for the selected fields.

Parameters:

fields (Sequence[str] | str) – Field names to resolve for each row.
limit (int | None) – Maximum number of records to format. Formats all records when omitted.

Return type:

list[list[str]]

field_paths()[source]¶

Return discoverable field paths present in this record set.

Return type:: list[str]

unique_values(field)[source]¶

Return unique scalar values present for a field.

Return type:: list[JsonValue]

preview(*, fields='default', limit=10)[source]¶

Build a Rich table preview of the selected fields.

Return type:: Table

to_dataframe(fields=None)[source]¶

Convert the records to a pandas DataFrame when pandas is available.

Parameters:: fields (Sequence[str] | str | None) – Optional selected fields. Pass "default" to use compact display fields. When omitted, full record dictionaries are used.
Return type:: Any
Returns:: pandas.DataFrame containing the selected record data.
Raises:: ImportError – If pandas is not installed.

to_display_dataframe(fields='default')[source]¶

Convert compact display rows to a pandas DataFrame.

Return type:: Any

default_fields()[source]¶

Return default display fields for this record set.

Return type:: list[str]