roboto.query#

Submodules#

Package Contents#

class roboto.query.BaseVisitor#

Bases: ConditionVisitor

Query base visitor

visit_condition(condition)#

Parameters:: condition (roboto.query.conditions.Condition)
Return type:: Optional[roboto.query.conditions.ConditionType]

visit_condition_group(condition_group)#

Parameters:: condition_group (roboto.query.conditions.ConditionGroup)
Return type:: Optional[roboto.query.conditions.ConditionType]

class roboto.query.BooleanFilter(/, **data)#

Bases: _FilterBase

True or false, or unset.

Parameters:: data (Any)

comparator: Literal[roboto.query.conditions.Comparator.Equals, roboto.query.conditions.Comparator.IsNull, roboto.query.conditions.Comparator.IsNotNull]#

type: Literal['boolean'] = 'boolean'#

values: list[bool] = None#

class roboto.query.Comparator#

Bases: roboto.compat.StrEnum

The comparator to use when comparing a field to a value.

BeginsWith = 'BEGINS_WITH'#

Contains = 'CONTAINS'#

Equals = 'EQUALS'#

Exists = 'EXISTS'#

GreaterThan = 'GREATER_THAN'#

GreaterThanOrEqual = 'GREATER_THAN_OR_EQUAL'#

IsNotNull = 'IS_NOT_NULL'#

IsNull = 'IS_NULL'#

LessThan = 'LESS_THAN'#

LessThanOrEqual = 'LESS_THAN_OR_EQUAL'#

Like = 'LIKE'#

NotContains = 'NOT_CONTAINS'#

NotEquals = 'NOT_EQUALS'#

NotExists = 'NOT_EXISTS'#

NotLike = 'NOT_LIKE'#

static from_string(value)#

Parameters:: value (str)
Return type:: Comparator

to_compact_string()#

class roboto.query.Condition(/, **data)#

Bases: pydantic.BaseModel

A filter for any arbitrary attribute for a Roboto resource.

Parameters:: data (Any)

comparator: Comparator#

classmethod equals_cond(field, value)#

Parameters:

field (str)
value (ConditionValue)

Return type:

Condition

field: Annotated[str, Field]#

matches(target)#

Parameters:: target (dict)
Return type:: bool

target_unspecified()#

Is the target resource of this query condition unspecified?

Return type:: bool

targets_dataset()#

Does this query condition target a dataset?

Return type:: bool

targets_file()#

Does this query condition target a file?

Return type:: bool

targets_message_path()#

Does this query condition target a message path?

Return type:: bool

targets_topic()#

Does this query condition target a topic?

Return type:: bool

value: ConditionValue = None#

class roboto.query.ConditionGroup(/, **data)#

Bases: pydantic.BaseModel

A group of conditions that are combined together.

Parameters:: data (Any)

static and_group(*conditions)#

Parameters:: conditions (ConditionType)
Return type:: ConditionGroup

conditions: collections.abc.Sequence[ConditionType]#

matches(target)#

Parameters:: target (dict | Callable[[ConditionType], bool])

operator: ConditionOperator#

static or_group(*conditions)#

Parameters:: conditions (ConditionType)
Return type:: ConditionGroup

validate_conditions(v)#

Parameters:: v (collections.abc.Sequence[ConditionType])

class roboto.query.ConditionOperator#

Bases: roboto.compat.StrEnum

The operator to use when combining multiple conditions.

And = 'AND'#

Not = 'NOT'#

Or = 'OR'#

static from_string(value)#

Parameters:: value (str)
Return type:: ConditionOperator

roboto.query.ConditionType#

roboto.query.ConditionValue#

class roboto.query.ConditionVisitor#

Bases: abc.ABC

Query condition visitor

visit(cond)#

Parameters:: cond (roboto.query.conditions.ConditionType)
Return type:: Optional[roboto.query.conditions.ConditionType]

abstract visit_condition(condition)#

Parameters:: condition (roboto.query.conditions.Condition)
Return type:: Optional[roboto.query.conditions.ConditionType]

abstract visit_condition_group(condition_group)#

Parameters:: condition_group (roboto.query.conditions.ConditionGroup)
Return type:: Optional[roboto.query.conditions.ConditionType]

roboto.query.DEFAULT_PAGE_SIZE: int = 50#: Default page size for search.

class roboto.query.DateFilter(/, **data)#

Bases: _FilterBase

Instants and ranges. Values are ISO 8601 strings.

The only variant offering relative windows, which is where the fidelity problem this whole model exists for actually bites.

Parameters:: data (Any)

comparator: Literal[roboto.query.conditions.Comparator.LessThan, roboto.query.conditions.Comparator.GreaterThan, roboto.query.conditions.Comparator.IsNull, roboto.query.conditions.Comparator.IsNotNull, FilterOnlyComparator, FilterOnlyComparator, FilterOnlyComparator, FilterOnlyComparator, FilterOnlyComparator, FilterOnlyComparator]#

type: Literal['date'] = 'date'#

values: list[str] = None#

class roboto.query.EnumFilter(/, **data)#

Bases: _FilterBase

Equality against a closed set of options.

Parameters:: data (Any)

comparator: Literal[roboto.query.conditions.Comparator.Equals, roboto.query.conditions.Comparator.NotEquals, roboto.query.conditions.Comparator.IsNull, roboto.query.conditions.Comparator.IsNotNull]#

type: Literal['enum'] = 'enum'#

values: list[str] = None#

class roboto.query.Field(path)#

Bases: str

A string-like field path that parses resource qualifiers and extracts the target path.

Field extends str to provide automatic parsing of qualified field paths like “dataset.metadata.owner” or “topic.name” into their constituent parts. It identifies the target resource type (dataset, file, topic, or message_path) and extracts the actual field path within that resource.

The class supports both qualified paths (e.g., “dataset.org_id”) and unqualified paths (e.g., “org_id”). For qualified paths, it strips the resource prefix and stores both the original fully qualified path and the extracted target information.

Examples

>>> field = Field("dataset.metadata.foo")
>>> field.target.resource
'dataset'
>>> field.target.path
'metadata.foo'

>>> field = Field("org_id")
>>> field.target.resource is None
True
>>> field.target.path
'org_id'

Parameters:: path (str)

property target: FieldTarget#

Return type:: FieldTarget

classmethod wrap(field)#

Parameters:: field (Union[str, Field])
Return type:: Field

type roboto.query.Filter = Annotated[Union[StringFilter, NumericFilter, MetricFilter, DateFilter, BooleanFilter, SetFilter, EnumFilter, IdentityFilter], pydantic.Field(discriminator='type')]#: One filter row. type selects the variant, and with it the operators on offer.

class roboto.query.FilterMatchMode#

Bases: enum.StrEnum

How separate filters combine.

And = 'AND'#: Every filter must match.

Or = 'OR'#: At least one filter must match.

class roboto.query.FilterOnlyComparator#

Bases: enum.StrEnum

Operators a saved filter needs that Comparator cannot express.

Every member is a gap in the query language, and this enum is the list of them. It is deliberately the complement of Comparator rather than a superset: a member here that Comparator can express is a stale entry, and a test asserts the two never overlap.

The intended lifecycle is deletion. As Comparator grows to cover these (ENG-2957), members are removed one at a time; the wire values are unchanged by that move, so filters saved beforehand keep parsing. When this enum is empty, the work is done.

Between = 'BETWEEN'#: An inclusive range. Translates to GTE and LTE, which loses the fact that the author expressed one range rather than two independent bounds.

Last30Days = 'LAST_30_DAYS'#

Last7Days = 'LAST_7_DAYS'#

Last90Days = 'LAST_90_DAYS'#

ThisMonth = 'THIS_MONTH'#

Relative windows, resolved against “now” when the filter runs.

These are the members that matter. The others cost fidelity; these cost correctness — a resolved window is wrong the day after it is saved, and nothing about the stored value says so.

Today = 'TODAY'#

class roboto.query.IdentityComparator#

Bases: enum.StrEnum

Operators over a principal-valued field, where the operator names a principal type.

An audit column such as created_by stores a fully-qualified principal — user:<user_id>, device:<device_id>@<org_id>, invocation:<invocation_id> — so “created by a user” is a question about the type prefix and “created by this user” a question about the whole value. Putting the type in the operator is what lets a filter UI offer the matching directory to pick from, instead of asking for a hand-typed prefix.

Each type contributes two operators (see IDENTITY_OPERATORS_BY_TYPE): a value-bearing IS_<TYPE> and a valueless IS_ANY_<TYPE>.

Separate from FilterOnlyComparator because these are not gaps in the query language. Both halves are expressible today — IS_<TYPE> as EQUALS against each picked principal, IS_ANY_<TYPE> as LIKE '<type>:%' — so ENG-2957 will never delete them. They are a filter-UI affordance, and they outlive the gap enum.

IsAnyDevice = 'IS_ANY_DEVICE'#

IsAnyIntegration = 'IS_ANY_INTEGRATION'#

IsAnyInvocation = 'IS_ANY_INVOCATION'#

IsAnyOrg = 'IS_ANY_ORG'#

IsAnyUser = 'IS_ANY_USER'#

IsDevice = 'IS_DEVICE'#

IsIntegration = 'IS_INTEGRATION'#

IsInvocation = 'IS_INVOCATION'#

IsOrg = 'IS_ORG'#

IsUser = 'IS_USER'#

class roboto.query.IdentityFilter(/, **data)#

Bases: _FilterBase

A principal-valued field, filtered by principal type.

Audit columns (created_by, modified_by) hold a fully-qualified principal string, so the operator names the type (IdentityComparator) and any values it takes are principals of that type — an IS_USER filter carrying a device: value is rejected, since it records an intent the picker cannot express and a query cannot satisfy.

Values are labeled options rather than bare strings: a principal id is not a name a reader can place, so the directory’s display name is captured alongside it at pick time.

Has no presence axis. Every write path stamps an audit principal, so the column is never null and a null check would be an operator that always answers the same way.

Parameters:: data (Any)

comparator: Literal[IdentityComparator, IdentityComparator, IdentityComparator, IdentityComparator, IdentityComparator, IdentityComparator, IdentityComparator, IdentityComparator, IdentityComparator, IdentityComparator]#

type: Literal['identity'] = 'identity'#

values: list[LabeledOption] = None#

class roboto.query.LabeledOption(/, **data)#

Bases: pydantic.BaseModel

One option as it was picked: the value a query is built from, plus what the picker showed.

Both halves are stored because the label cannot be recovered later. An opaque value — user:usr_01J..., a tag id — renders as itself, and resolving it on load would mean a directory lookup per chip, against an org that whoever opens a shared View may not be able to read. Only value ever reaches a query.

Parameters:: data (Any)

label: str#: What the picker displayed when the author chose this option. Display only, never queried.

model_config#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

value: str#: What the query is built from. A fully-qualified principal, for an identity filter.

roboto.query.MAX_PAGE_SIZE: int = 1000#: Maximum allowable page size for search.

roboto.query.METRIC_FIELD_PATTERN: Final[str] = '^metric\\..+'#

roboto.query.METRIC_FIELD_PREFIX: Final[str] = 'metric.'#

Prefix distinguishing a user-defined metric from an ordinary numeric property.

Metric filters store the prefixed form so that field means the same thing here as it does in a Condition, and so the eventual migration to a query copies the field across rather than special-casing it.

class roboto.query.MetricFilter(/, **data)#

Bases: _FilterBase

Ordering and equality over a user-defined metric.

Numeric in every respect except that field is a metric path. Kept a distinct variant so a client restoring a View knows to reopen the metric picker rather than the property form, which it cannot infer from the field name alone.

Carries the presence pair like any other scalar type. A session may simply have no such metric recorded, and the session query path answers that directly — it maps IS_NULL to a NOT EXISTS over the metrics table.

Parameters:: data (Any)

comparator: Literal[roboto.query.conditions.Comparator.Equals, roboto.query.conditions.Comparator.NotEquals, roboto.query.conditions.Comparator.GreaterThan, roboto.query.conditions.Comparator.LessThan, roboto.query.conditions.Comparator.GreaterThanOrEqual, roboto.query.conditions.Comparator.LessThanOrEqual, roboto.query.conditions.Comparator.IsNull, roboto.query.conditions.Comparator.IsNotNull]#

field: MetricField#: The field being filtered, as the query layer addresses it.

type: Literal['metric'] = 'metric'#

unit: str | None = None#

The metric’s unit, copied from its definition when the filter was built.

Denormalized for display: the filter chip renders it beside the value (“path_deviation > 1.5 m”) without looking the definition up. None when the definition declares no unit.

Being a copy, it goes stale if the definition’s unit later changes — a saved View would render the old one. Tolerable while it is only a label, and an argument for view_v2 resolving it from the definition rather than storing it. See ENG-2957.

values: list[float] = None#

class roboto.query.NumericFilter(/, **data)#

Bases: _FilterBase

Ordering and equality over a numeric property.

Parameters:: data (Any)

comparator: Literal[roboto.query.conditions.Comparator.Equals, roboto.query.conditions.Comparator.NotEquals, roboto.query.conditions.Comparator.GreaterThan, roboto.query.conditions.Comparator.LessThan, roboto.query.conditions.Comparator.GreaterThanOrEqual, roboto.query.conditions.Comparator.LessThanOrEqual, roboto.query.conditions.Comparator.IsNull, roboto.query.conditions.Comparator.IsNotNull]#

type: Literal['numeric'] = 'numeric'#

values: list[float] = None#

class roboto.query.QualifiedRoboqlQuery(/, **data)#

Bases: pydantic.BaseModel

A RoboQL query which has been qualified with a target.

Parameters:: data (Any)

query: str = None#

target: QueryTarget = None#

type roboto.query.Query = Union[RoboQLQuery, QuerySpecification]#

class roboto.query.QueryClient(roboto_client=None, owner_org_id=None, roboto_profile=None)#

A low-level Roboto query client. Prefer RobotoSearch for a simpler, more curated query interface.

Parameters:

roboto_client (Optional[roboto.http.RobotoClient])
owner_org_id (Optional[str])
roboto_profile (Optional[str])

are_query_results_available(query_id, owner_org_id=None)#

Parameters:

query_id (str)
owner_org_id (Optional[str])

Return type:

bool

get_query_record(query_id, owner_org_id=None)#

Parameters:

query_id (str)
owner_org_id (Optional[str])

Return type:

roboto.query.api.QueryRecord

get_query_results(query_id, owner_org_id=None)#

Parameters:

query_id (str)
owner_org_id (Optional[str])

Return type:

collections.abc.Generator[dict[str, Any], None, None]

property roboto_client: roboto.http.RobotoClient#

Return type:: roboto.http.RobotoClient

submit_query(query, target, timeout_seconds, content_mode=QueryContentMode.RecordWithMeta, owner_org_id=None)#

Parameters:

query (Optional[Query])
target (roboto.query.api.QueryTarget)
timeout_seconds (float)
content_mode (roboto.query.api.QueryContentMode)
owner_org_id (Optional[str])

Return type:

collections.abc.Generator[dict[str, Any], None, None]

submit_roboql(request, owner_org_id=None)#

Parameters:

request (roboto.query.api.SubmitRoboqlQueryRequest)
owner_org_id (Optional[str])

Return type:

roboto.query.api.QueryRecord

submit_roboql_and_await_results(request, timeout_seconds, owner_org_id=None)#

Parameters:

request (roboto.query.api.SubmitRoboqlQueryRequest)
timeout_seconds (float)
owner_org_id (Optional[str])

Return type:

collections.abc.Generator[dict[str, Any], None, None]

submit_structured(request, owner_org_id=None)#

Parameters:

request (roboto.query.api.SubmitStructuredQueryRequest)
owner_org_id (Optional[str])

Return type:

roboto.query.api.QueryRecord

submit_structured_and_await_results(request, timeout_seconds, owner_org_id=None)#

Parameters:

request (roboto.query.api.SubmitStructuredQueryRequest)
timeout_seconds (float)
owner_org_id (Optional[str])

Return type:

collections.abc.Generator[dict[str, Any], None, None]

submit_term(request, owner_org_id=None)#

Parameters:

request (roboto.query.api.SubmitTermQueryRequest)
owner_org_id (Optional[str])

Return type:

roboto.query.api.QueryRecord

submit_term_and_await_results(request, timeout_seconds=math.inf, owner_org_id=None)#

Parameters:

request (roboto.query.api.SubmitTermQueryRequest)
timeout_seconds (float)
owner_org_id (Optional[str])

Return type:

collections.abc.Generator[dict[str, Any], None, None]

class roboto.query.QueryContentMode#

Bases: roboto.compat.StrEnum

Hint to query APIs on whether to return Roboto entities with custom metadata.

In RecordOnly mode, Roboto entities are returned without custom metadata, ensuring a smaller and more predictable response size. Use this mode when you need lower query latency, larger result page sizes, or both.

In RecordWithMeta mode, Roboto entities are returned with all available custom metadata. Use this mode if you need immediate access to metadata fields.

Note: content mode support is initially available for dataset queries, and will be added incrementally for other entity types.

RecordOnly = 'record_only'#

Query results are returned with core Roboto data attributes only.

Those attributes establish the identity and function of Roboto entities.

RecordWithMeta = 'record_with_meta'#

Query results are returned with all available entity attributes.

This includes core Roboto data attributes as well as custom metadata.

class roboto.query.QueryContext(/, **data)#

Bases: pydantic.BaseModel

Context for a query

Parameters:: data (Any)

query: dict[str, Any] = None#

query_scheme: QueryScheme#

class roboto.query.QueryRecord(/, **data)#

Bases: pydantic.BaseModel

A wire-transmissible representation of a query.

Parameters:: data (Any)

modified: datetime.datetime = None#

org_id: str = None#

query_ctx: QueryContext = None#

query_id: str = None#

result_count: int = None#

status: QueryStatus = None#

submitted: datetime.datetime = None#

submitted_by: str = None#

target: QueryTarget = None#

class roboto.query.QueryScheme#

Bases: roboto.compat.StrEnum

A specific query format/schema which can be used in combination with some context JSON to provide all information required to execute a query.

QuerySpecV1 = 'query_spec_v1'#: The initial variant of roboto.query.QuerySpecification which powered search since mid 2023.

class roboto.query.QuerySpecification(/, **data)#

Bases: pydantic.BaseModel

Model for specifying a query to the Roboto Platform.

Examples

Specify a query with a single condition:

>>> from roboto import query
>>> query_spec = query.QuerySpecification(
...     condition=query.Condition(field="name", comparator=query.Comparator.Equals, value="Roboto")
... )

Specify a query with multiple conditions:

>>> from roboto import query
>>> query_spec = query.QuerySpecification(
...     condition=query.ConditionGroup(
...         operator=query.ConditionOperator.And,
...         conditions=[
...             query.Condition(field="name", comparator=query.Comparator.Equals, value="Roboto"),
...             query.Condition(field="age", comparator=query.Comparator.GreaterThan, value=18),
...         ],
...     )
... )

Arbitrarily nest condition groups:

>>> from roboto import query
>>> query_spec = query.QuerySpecification(
...     condition=query.ConditionGroup(
...         operator=query.ConditionOperator.And,
...         conditions=[
...             query.Condition(field="name", comparator=query.Comparator.Equals, value="Roboto"),
...             query.ConditionGroup(
...                 operator=query.ConditionOperator.Or,
...                 conditions=[
...                     query.Condition(field="age", comparator=query.Comparator.GreaterThan, value=18),
...                     query.Condition(field="age", comparator=query.Comparator.LessThan, value=30),
...                 ],
...             ),
...         ],
...     )
... )

Parameters:: data (Any)

after: str | None = None#: Encoded next page token. Optional.

condition: roboto.query.conditions.Condition | roboto.query.conditions.ConditionGroup | None = None#: Query condition(s) to evaluate when looking up Roboto entities.

fields()#

Return a set of all fields referenced in the query.

Return type:: set[str]

limit: int = 1000#: Page size for returned results. Optional, default is MAX_PAGE_SIZE.

max_results: int | None = None#

Maximum number of results to return across all pages. Must be >= 1 when set. None (default) means no cap — pagination yields the full result set. Distinct from limit, which is the per-page size.

Only honored for queries executed via Roboto search (the QueryTarget resource types: collections, datasets, devices, files, sessions, topics, topic message paths, events). Other code paths that accept a QuerySpecification ignore this field.

model_config#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

sort_by: str | None = None#: Field to sort results by. Optional, defaults to created date (created).

sort_direction: SortDirection | None = None#: Sort direction for query results. Optional, defaults to “descending”.

class roboto.query.QueryStatus(*args, **kwds)#

Bases: enum.Enum

The query lifecycle state of a given query.

Failed = 'failed'#: Indicates the query failed to execute.

ResultsAvailable = 'results_available'#

Indicates that query results are available for clients to retrieve.

Results might be available immediately, such as in paginated database search, or once a (potentially expensive) calculation completes for more advanced search modalities.

Scheduled = 'scheduled'#: Indicates the query is scheduled for execution.

class roboto.query.QueryStorageContext(/, **data)#

Bases: pydantic.BaseModel

Context for query storage

Parameters:: data (Any)

storage_ctx: dict[str, Any] = None#

storage_scheme: QueryStorageScheme#

class roboto.query.QueryStorageScheme#

Bases: roboto.compat.StrEnum

A specific query result storage format/schema which can be used in combination with some context JSON to provide all information required to vend query results

S3ManifestV1 = 's3_manifest_v1'#: Query results are in S3, and a manifest file enumerates the result parts and how to resolve them into rows.

class roboto.query.QueryTarget#

Bases: roboto.compat.StrEnum

The type of resource a specific query is requesting.

Collections = 'collections'#

Datasets = 'datasets'#

Devices = 'devices'#

Events = 'events'#

Files = 'files'#

Sessions = 'sessions'#

TopicMessagePaths = 'topic_message_paths'#

Topics = 'topics'#

class roboto.query.SavedFilters(/, **data)#

Bases: pydantic.BaseModel

A complete set of filter controls, as saved.

Parameters:: data (Any)

filters: list[Filter] = None#: The rows, in the order the author added them.

match_mode: FilterMatchMode#

Whether the rows are combined with AND or OR.

Deliberately a single flag rather than a nested boolean expression. A Condition can express arbitrary nesting, but a filter UI cannot build one legibly, so this records the shape the UI actually offers.

model_config#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class roboto.query.SetFilter(/, **data)#

Bases: _FilterBase

Membership in a collection-valued field, such as tags.

Has no presence axis: an empty collection is not the same as an absent one, and the UI offers no null check here.

Parameters:: data (Any)

comparator: Literal[roboto.query.conditions.Comparator.Contains, roboto.query.conditions.Comparator.NotContains]#

type: Literal['set'] = 'set'#

values: list[str] = None#

class roboto.query.SortDirection#

Bases: roboto.compat.StrEnum

The direction to sort the results of a query.

Ascending = 'ASC'#

Descending = 'DESC'#

static from_string(value)#

Parameters:: value (str)
Return type:: SortDirection

class roboto.query.StringFilter(/, **data)#

Bases: _FilterBase

Text matching.

Parameters:: data (Any)

comparator: Literal[roboto.query.conditions.Comparator.Equals, roboto.query.conditions.Comparator.NotEquals, roboto.query.conditions.Comparator.Contains, roboto.query.conditions.Comparator.NotContains, roboto.query.conditions.Comparator.Like, roboto.query.conditions.Comparator.NotLike, roboto.query.conditions.Comparator.IsNull, roboto.query.conditions.Comparator.IsNotNull]#

type: Literal['string'] = 'string'#

values: list[str] = None#

class roboto.query.SubmitRoboqlQueryRequest(/, **data)#

Bases: pydantic.BaseModel

Request payload to submit a RoboQL query

Parameters:: data (Any)

content_mode: QueryContentMode = None#

query: str | None = None#

target: QueryTarget = None#

class roboto.query.SubmitStructuredQueryRequest(/, **data)#

Bases: pydantic.BaseModel

Request payload to submit a structured query

Parameters:: data (Any)

content_mode: QueryContentMode = None#

query: roboto.query.specification.QuerySpecification = None#

target: QueryTarget = None#

class roboto.query.SubmitTermQueryRequest(/, **data)#

Bases: pydantic.BaseModel

Request payload to submit a simple term query

Parameters:: data (Any)

content_mode: QueryContentMode = None#

target: QueryTarget = None#

term: str = None#