roboto.query.api

Module Contents

roboto.query.api.MAX_VALUE_COUNTS_LIMIT: int = 1000

the most values one ValueCounts lists.

Type:

The largest and the default ValueCountsSpec.limit

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

Bases: pydantic.BaseModel

A RoboQL query which has been qualified with a target.

Parameters:

data (Any)

query: str

target: QueryTarget

class roboto.query.api.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.api.QueryContext(/, **data)

Bases: pydantic.BaseModel

Context for a query

Parameters:

data (Any)

query: dict[str, Any]

query_scheme: QueryScheme

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

Bases: pydantic.BaseModel

A wire-transmissible representation of a query.

Parameters:

data (Any)

modified: datetime.datetime

org_id: str

query_ctx: QueryContext

query_id: str

result_count: int

status: QueryStatus

submitted: datetime.datetime

submitted_by: str

target: QueryTarget

class roboto.query.api.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.api.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.api.QueryStorageContext(/, **data)

Bases: pydantic.BaseModel

Context for query storage

Parameters:

data (Any)

storage_ctx: dict[str, Any]

storage_scheme: QueryStorageScheme

class roboto.query.api.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.api.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.api.SubmitRoboqlQueryRequest(/, **data)

Bases: pydantic.BaseModel

Request payload to submit a RoboQL query

Parameters:

data (Any)

content_mode: QueryContentMode

query: str | None

target: QueryTarget

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

Bases: pydantic.BaseModel

Request payload to submit a structured query

Parameters:

data (Any)

content_mode: QueryContentMode

query: roboto.query.specification.QuerySpecification

target: QueryTarget

value_counts: ValueCountsSpec | None

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

Bases: pydantic.BaseModel

Request payload to submit a simple term query

Parameters:

data (Any)

content_mode: QueryContentMode

target: QueryTarget

term: str

class roboto.query.api.ValueCount(/, **data)

Bases: pydantic.BaseModel

One value of the counted field, and how many of the matched records hold it.

Parameters:

data (Any)

count: int

first_time: int | str | None

last_time: int | str | None

value: Any

class roboto.query.api.ValueCounts(/, **data)

Bases: pydantic.BaseModel

Response of GET /v1/query/id/<query_id>/value-counts: the values of the field the query’s ValueCountsSpec names, over the records the query matches.

Parameters:

data (Any)

distinct_values: int

field: str

matched: int

property truncated: bool

True when the matched records hold more distinct values than values lists.

Return type:

bool

values: list[ValueCount]

without_value: int

class roboto.query.api.ValueCountsSpec(/, **data)

Bases: pydantic.BaseModel

A request to count how many of the records a query matches hold each value of one field. Submit it as SubmitStructuredQueryRequest.value_counts, then read the ValueCounts with GET /v1/query/id/<query_id>/value-counts. The endpoint is enabled per caller; a caller it is not enabled for gets RobotoFeatureNotAvailableException.

Supported for the events, sessions, datasets, devices, collections, and files query targets. Every record the query’s condition matches is counted: the query’s sort_by, sort_direction, limit, after and max_results do not apply.

Parameters:

data (Any)

field: str

limit: int

time_field: str | None