Resolve read plans by schema

Resolve one read plan for each schema a topic has in a window, beside each schema that can’t be planned.

Authorization is that of :py:func:resolve_read_plan: all-or-nothing over the window, so a caller who cannot view every in-window partition’s file gets a 401 and no plans. A field no schema of the topic declares is a 400 (RobotoUnknownFieldAddressException), even over an empty window.

Access control

Restricted tokens need the API scope api.everything_else

POST/v2/topics/id/{topic_id}/read-plans-by-schema

Authorization

AuthorizationBearer token · headerrequired

Path parameters

topic_idstringrequired

Header parameters

X-Roboto-Org-Idstring

X-Roboto-User-Idstring

Request body

requiredapplication/json

fields_includeFieldAddress[]required

Show properties

Array of FieldAddress

pathstring[] | null

default: null

Show properties

Any of:

string[]

Array of string

string

null

null

field_idstring | null

default: null

Show properties

Any of:

string

string

null

null

start_timeinteger | null

default: null

Show properties

Any of:

integer

integer

null

null

end_timeinteger | null

default: null

Show properties

Any of:

integer

integer

null

null

preferRepresentationPreference | null

default: null

Show properties

Any of:

RepresentationPreference

defaultRepresentationSelector

Describes the stored variants a representation choice accepts.

The optional criteria storage_format, content_format, and transformations constrain the corresponding attributes of :py:class:RepresentationRecord. A variant must meet every criterion that is set; None places no requirement on that attribute.

:py:class:~roboto.experimental.topics.RepresentationPreference determines which selectors are tried and whether missing coverage is refused. Missing coverage under a last selector with no criteria has the meaning documented by :py:attr:~roboto.experimental.topics.ReadPlanPartition.scan_tasks.

Successor to :py:class:roboto.domain.topics.RepresentationSelector, used by :py:meth:~roboto.domain.topics.Topic.get_data.

default: {"storage_format":null,"content_format":null,"transformations":null}

Show properties

storage_formatRepresentationStorageFormat | null

default: null

Show properties

Any of:

RepresentationStorageFormat

string

null

null

content_formatstring | null

default: null

Show properties

Any of:

string

string

null

null

transformationsstring[] | null

default: null

Show properties

Any of:

string[]

Array of string

string

null

null

fallbacksRepresentationSelector[]

default: []

Show properties

Array of RepresentationSelector

storage_formatRepresentationStorageFormat | null

default: null

Show properties

Any of:

RepresentationStorageFormat

string

null

null

content_formatstring | null

default: null

Show properties

Any of:

string

string

null

null

transformationsstring[] | null

default: null

Show properties

Any of:

string[]

Array of string

string

null

null

overridesRepresentationOverride[]

default: []

Show properties

Array of RepresentationOverride

fieldFieldAddressrequired

Addresses a schema field, and the subtree nested under it, by exactly one of two forms.

A path names the field by its path_in_schema components directly (no string delimiter, so a component may itself contain a .); a field_id names it opaquely and resolves server-side to the same path. Either form designates the field and every field nested under it.

Show properties

pathstring[] | null

default: null

Show properties

Any of:

string[]

Array of string

string

null

null

field_idstring | null

default: null

Show properties

Any of:

string

string

null

null

selectorRepresentationSelectorrequired

Describes the stored variants a representation choice accepts.

Successor to :py:class:roboto.domain.topics.RepresentationSelector, used by :py:meth:~roboto.domain.topics.Topic.get_data.

Show properties

storage_formatRepresentationStorageFormat | null

default: null

Show properties

Any of:

RepresentationStorageFormat

RepresentationStorageFormat

null

null

content_formatstring | null

default: null

Show properties

Any of:

string

string

null

null

transformationsstring[] | null

default: null

Show properties

Any of:

string[]

Array of string

string

null

null

null

null

timeline_source_namestring | null

default: null

Show properties

Any of:

string

string

null

null

session_idstring | null

default: null

Show properties

Any of:

string

string

null

null

file_idstring | null

default: null

Show properties

Any of:

string

string

null

null

dataset_idstring | null

default: null

Show properties

Any of:

string

string

null

null

device_idstring | null

default: null

Show properties

Any of:

string

string

null

null

Responses

200

dataobjectrequired

Response body of POST /v2/topics/id/<topic_id>/read-plans-by-schema: a read across schemas, resolved.

Each schema in the window, under the request's restrictions, has either a read plan in :py:attr:plans or a refusal in :py:attr:refusals, never both. Both lists are sorted by schema id.

Show properties

plansReadPlan[]required

Show properties

Array of ReadPlan

plan_versioninteger

default: 1

topic_idstringrequired

windowTimeWindow | nullrequired

Show properties

Any of:

TimeWindow

startintegerrequired

endintegerrequired

null

null

schemaReadPlanSchemaRef | null

default: null

Show properties

Any of:

ReadPlanSchemaRef

schema_idstringrequired

checksumstringrequired

named_arraysReadPlanNamedArray[]

default: []

Show properties

Array of ReadPlanNamedArray

field_idstringrequired

pathstring[]required

element_namesstring[]required

null

null

projectionReadPlanProjectionrequired

The output fields the plan resolves rows to.

The projection takes exactly one of two forms: either every field in the schema (all is true, and the field list is left implicit so the plan need not enumerate a large schema) or an explicit fields list.

Show properties

allboolean

default: false

fieldsReadPlanFieldRef[] | null

default: null

Show properties

Any of:

ReadPlanFieldRef[]

Array of ReadPlanFieldRef

field_idstringrequired

pathstring[]required

elementsstring[] | null

default: null

Show properties

Any of:

string[]

Array of string

string

null

null

null

null

partitionsReadPlanPartition[]

default: []

Show properties

Array of ReadPlanPartition

topic_part_idstringrequired

time_offset_nsintegerrequired

windowTimeWindowrequired

An interval of time in absolute nanoseconds since the Unix epoch, inclusive at both ends.

A read plan uses this type for three intervals: the window that the plan was resolved over (:py:attr:ReadPlan.window), the window that selects each partition's rows (:py:attr:ReadPlanPartition.window), and each partition's :py:attr:ReadPlanPartition.timeline_extent. Because all three share this shape, a consumer can intersect any two of them directly.

Show properties

startintegerrequired

endintegerrequired

timeline_extentTimeWindowrequired

An interval of time in absolute nanoseconds since the Unix epoch, inclusive at both ends.

Show properties

startintegerrequired

endintegerrequired

timestampReadPlanTimestamprequired

Where a partition's row timestamps come from.

Timestamps are either read out of a schema field (kind is "schema_field", and field names which one) or taken from the storage envelope (message log or publish time), in which case no schema field is involved and field is None.

Show properties

kindstringrequired

Allowed:schema_fieldmessage_log_timemessage_publish_time

fieldReadPlanFieldRef | null

default: null

Show properties

Any of:

ReadPlanFieldRef

ReadPlanFieldRef

null

null

unitstring | null

default: null

Show properties

Any of:

string

string

null

null

source_namestring | null

default: null

Show properties

Any of:

string

string

null

null

data_rangeany[] | null

default: null

Show properties

Any of:

any[]

Array of any

null

null

scan_tasksReadPlanScanTask[]

default: []

Show properties

Array of ReadPlanScanTask

subtreeReadPlanFieldRef | null

default: null

Show properties

Any of:

ReadPlanFieldRef

ReadPlanFieldRef

null

null

precedenceintegerrequired

formatRepresentationStorageFormatrequired

Supported storage formats for topic data representations.

Defines the available formats for storing and accessing topic data within the Roboto platform. Each format has different characteristics and use cases.

Allowed:mcapparquet

transformationsstring[]

default: []

objectReadPlanObjectRefrequired

Points to the file backing a scan task. A consumer fetches the file's bytes from it.

Show properties

fs_node_idstringrequired

size_bytesinteger | null

default: null

Show properties

Any of:

integer

integer

null

null

versioninteger | null

default: null

Show properties

Any of:

integer

integer

null

null

topic_namestring | null

default: null

Show properties

Any of:

string

string

null

null

fs_node_idstring | null

default: null

Show properties

Any of:

string

string

null

null

refusalsSchemaPlanRefusal[]required

Show properties

Array of SchemaPlanRefusal

schema_idstringrequired

error_codestringrequired

messagestringrequired

windowTimeWindowrequired

An interval of time in absolute nanoseconds since the Unix epoch, inclusive at both ends.

Show properties

startintegerrequired

endintegerrequired

timeline_source_namesstring[] | null

default: null

Show properties

Any of:

string[]

Array of string

string

null

null

400

Thrown when the conversation context (messages, system prompt, tool results) exceeds the model's context window limit.

The token estimate and the model's context limit are not carried on the exception, so a caller cannot read usage numbers off it.

errorobject

Show properties

error_codenumber

messagestring

stack_tracestring | null

401

Thrown when authentication fails

errorobject

Show properties

error_codenumber

messagestring

stack_tracestring | null

403

Thrown if an operation would exceed a user or org level limit.

errorobject

Show properties

error_codenumber

messagestring

stack_tracestring | null

404

Thrown if a user is attempting to perform an action unrecognized by the Roboto platform.

errorobject

Show properties

error_codenumber

messagestring

stack_tracestring | null

409

Thrown if there is a conflict between a resource you're creating and another existing resource

errorobject

Show properties

error_codenumber

messagestring

stack_tracestring | null

410

Thrown if a resource is missing or expired.

errorobject

Show properties

error_codenumber

messagestring

stack_tracestring | null

500

An error the platform reported that this SDK release cannot resolve to a specific exception class.

Reported for an element of a :py:class:~roboto.http.BatchResponse whose error names a code this release defines no class for, or that arrived without a code, without a message, or as text that is not an error envelope at all. It carries whatever code and message the platform sent, so a caller handling the failure still learns what went wrong; when no message could be read, the message is the error's raw text.

The error envelope carries no status code, so http_status_code reports the 500 inherited from :py:class:RobotoDomainException rather than the status the failure actually had.

errorobject

Show properties

error_codenumber

messagestring

stack_tracestring | null

501

Thrown by shimmed out APIs which have not yet been implemented

errorobject

Show properties

error_codenumber

messagestring

stack_tracestring | null

503

Thrown when a service is unavailable, such as when it's under heavy load and can't accept new requests. This is expected to be transient and ought to be retried.

errorobject

Show properties

error_codenumber

messagestring

stack_tracestring | null

504

Thrown when the service times out while processing a request. This is exepcted to be transient and ought to be retried.

errorobject

Show properties

error_codenumber

messagestring

stack_tracestring | null

507

Thrown when the server cannot complete the request because the response payload exceeds a storage or transport capacity limit (e.g., Lambda response size). This is NOT expected to be transient and should NOT be retried.

errorobject

Show properties

error_codenumber

messagestring

stack_tracestring | null

Try it

Server

Base URLCustom base URLOverrides the selected server when set.

Authorization

Bearer tokenRemember on this deviceInclude my values in samples

Parameters

X-Roboto-Org-IdheaderX-Roboto-User-Idheadertopic_idpath*

Bodyapplication/json

Request body

Request

curl -X POST 'https://api.roboto.ai/v2/topics/id/string/read-plans-by-schema' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "fields_include": [
    {
      "path": null,
      "field_id": null
    }
  ],
  "start_time": null,
  "end_time": null,
  "prefer": null,
  "timeline_source_name": null,
  "session_id": null,
  "file_id": null,
  "dataset_id": null,
  "device_id": null
}'

const response = await fetch("https://api.roboto.ai/v2/topics/id/string/read-plans-by-schema", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Accept": "application/json",
    "Content-Type": "application/json"
  },
  body: "{\n  \"fields_include\": [\n    {\n      \"path\": null,\n      \"field_id\": null\n    }\n  ],\n  \"start_time\": null,\n  \"end_time\": null,\n  \"prefer\": null,\n  \"timeline_source_name\": null,\n  \"session_id\": null,\n  \"file_id\": null,\n  \"dataset_id\": null,\n  \"device_id\": null\n}"
});

import requests

response = requests.post(
    "https://api.roboto.ai/v2/topics/id/string/read-plans-by-schema",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Accept": "application/json",
        "Content-Type": "application/json"
    },
    data="{\n  \"fields_include\": [\n    {\n      \"path\": null,\n      \"field_id\": null\n    }\n  ],\n  \"start_time\": null,\n  \"end_time\": null,\n  \"prefer\": null,\n  \"timeline_source_name\": null,\n  \"session_id\": null,\n  \"file_id\": null,\n  \"dataset_id\": null,\n  \"device_id\": null\n}",
)

Response

{
  "data": {
    "plans": [
      {
        "plan_version": 1,
        "topic_id": "string",
        "window": {
          "start": 0,
          "end": 0
        },
        "schema": null,
        "projection": {
          "all": false,
          "fields": null
        },
        "partitions": []
      }
    ],
    "refusals": [
      {
        "schema_id": "string",
        "error_code": "string",
        "message": "string",
        "window": {
          "start": 0,
          "end": 0
        },
        "timeline_source_names": null
      }
    ]
  }
}

{
  "error": {
    "error_code": 0,
    "message": "string",
    "stack_trace": "string"
  }
}

{
  "error": {
    "error_code": 0,
    "message": "string",
    "stack_trace": "string"
  }
}

{
  "error": {
    "error_code": 0,
    "message": "string",
    "stack_trace": "string"
  }
}

{
  "error": {
    "error_code": 0,
    "message": "string",
    "stack_trace": "string"
  }
}

{
  "error": {
    "error_code": 0,
    "message": "string",
    "stack_trace": "string"
  }
}

{
  "error": {
    "error_code": 0,
    "message": "string",
    "stack_trace": "string"
  }
}

{
  "error": {
    "error_code": 0,
    "message": "string",
    "stack_trace": "string"
  }
}

{
  "error": {
    "error_code": 0,
    "message": "string",
    "stack_trace": "string"
  }
}

{
  "error": {
    "error_code": 0,
    "message": "string",
    "stack_trace": "string"
  }
}

{
  "error": {
    "error_code": 0,
    "message": "string",
    "stack_trace": "string"
  }
}

{
  "error": {
    "error_code": 0,
    "message": "string",
    "stack_trace": "string"
  }
}