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.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 = 100#: Default page size for search.

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

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

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, owner_org_id=None)#

Parameters:

query (Optional[Query])
target (roboto.query.api.QueryTarget)
timeout_seconds (float)
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.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.

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'#

Events = 'events'#

Files = 'files'#

TopicMessagePaths = 'topic_message_paths'#

Topics = 'topics'#

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.SubmitRoboqlQueryRequest(/, **data)#

Bases: pydantic.BaseModel

Request payload to submit a RoboQL query

Parameters:: data (Any)

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)

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)

target: QueryTarget = None#

term: str = None#