Search and record sets¶

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)[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.

select(*fields)[source]¶

Return JSON-friendly rows for the selected fields.

Return type:: list[MetadataDict]

rows(fields)[source]¶

Return JSON-friendly rows for the selected fields.

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

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

Return CLI-style display rows for the selected fields.

Parameters:

fields (Sequence[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=('id', 'title', 'product', 'species', 'path'), 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] | None) – Optional selected 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.