ibm/query-ado-data

Query ado Data

ado stores data in two places:

1. Metastore: Metadata about all resources (operations, discoveryspaces, samplestores, datacontainers, actuatorconfigurations)
2. Samplestores: Entities and measurements made on them

Guidelines

• When getting a list of resources the output will always be tabular formatted string
• Do not change context to answer a query unless specifically requested - metadata and data is context specific

Fast Querying

DOs:

• IMPORTANT Before deciding on what to query check the resource schema to confirm what is available in metadata - ado template RESOURCETYPE --include-schema
• Use Server side filtering
  • prefer --query or --matching to fetching metadata and filtering on client side
• Fetch metadata over fetching data
  • if a query can be answered via metadata it is much faster
  • filter via metadata first if possible, before obtaining data
  • IMPORTANT: ado show details space can be slow as it internally fetches spaces data to calculate - prefer using metadata
• Consider writing a script directly using SQLResourceStore API if the CLI is not expressive enough BEFORE fetching data
  • you can make batch requests e.g. getResources - much faster than one-by-one requests

DONTs

• Do not fetch discoveryspace or operation data for summary queries
  • Do not use: ado show entities, ado show requests, ado show results, ado show details)
  • Do not instantiating DiscoverySpace instances or SQLStore instance
• Only use these commands or classes when drilling down on a narrow set of resources

Using Resource models

Each resource has a pydantic model. If working in code you can use these models

• discoveryspace, orchestrator/core/discoveryspace/resource.py: DiscoverySpaceResource
• samplestore, orchestrator/core/samplestore/resource.py: SampleStoreResource
• datacontainer, orchestrator/core/datacontainer/resource.py: DataContainerResource
• operation, orchestrator/core/operation/resource.py: OperationResource
• actuatorconfiguration, orchestrator/core/actuatorconfiguration/resource.py: ActuatorConfigurationResource

Querying Metadata

Listing Resources

Get a general overview of what's present:

uv run ado get $RESOURCETYPE --details

Returns an age-sorted list (most recent last) of resources of the specified type.

Resource types: operations (op), discoveryspaces (space), samplestores (store), datacontainers (dcr), actuatorconfigurations (ac)

Filtering Resources

Filter resources based on metadata fields using MySQL JSON Path queries:

uv run ado get $RESOURCETYPE --query 'path=candidate'

• Use single quotes around the candidate (required for strings, dictionaries, arrays)
• Path is dot-separated (e.g., config.metadata.labels)
• Candidate is a valid JSON value
• Can specify --query multiple times (all filters must match)

Examples:

# Find operations using a specific operator
uv run ado get operations -q 'config.operation.module.moduleClass=RayTune'

# Find spaces with a specific experiment
uv run ado get spaces -q 'config.experiments={"experiments":{"identifier":"finetune-lora-fsdp-r-4-a-16-tm-default-v2.0.0"}}'

# Combine multiple filters
uv run ado get operations -q 'config.operation.parameters.batchSize=1'
-q 'status=[{"event": "finished", "exit_state": "success"}]'

For extensive examples, see website/docs/resources/metastore.md.

Filtering by Labels

Filter resources by labels:

uv run ado get $RESOURCETYPE -l key=value

Can specify multiple times (all labels must match):

uv run ado get operations -l labelone=valueone -l label_two=value_two

Matching Spaces

Find spaces matching a point or another space:

# Match spaces containing a specific entity point
uv run ado get space --matching-point point.yaml

# Match spaces similar to another space (by ID)
uv run ado get space --matching-space-id space-abc123-456def

# Match spaces similar to a space configuration (without creating it)
uv run ado get space --matching-space space.yaml

Note: --matching-point, --matching-space, and --matching-space-id are exclusive to spaces and override --query and --label.

Related Resources

Get IDs of resources related to another resource (parent or child):

uv run ado show related $RESOURCETYPE [RESOURCE_ID] [--use-latest]

Supported types: operation (op), samplestore (store), discoveryspace (space)

Example:

uv run ado show related space space-abc123-456def

Get Resource Details

View detailed information about a specific resource:

uv run ado show details $RESOURCETYPE [RESOURCE_ID] [--use-latest]

Querying Data

Show Entities

Get entities and their measurements from a space or operation:

uv run ado show entities RESOURCE_TYPE [RESOURCE_ID] \
                  [--use-latest] [--file | -f <file.yaml>]\
                  [--property-format {observed | target}] \
                  [--output | -o {console | csv | json}] \
                  [--output-file <path>] \
                  [--property <property-name>] \
                  [--include {sampled | matching | missing | unsampled}] \
                  [--aggregate {mean | median | variance | std | min | max}]

Resource types: operation (op), discoveryspace (space)

Key options:

• --include (spaces only): sampled, unsampled, matching, missing
• --property-format: observed (one row per entity) or target (one row per entity-experiment pair)
• --output (or -o): console, csv, or json
• --output-file specifies a file path to write the output to. If not provided, output is written to stdout.
• --property: Filter specific properties (can specify multiple times)
• --aggregate: Aggregate multiple values

Examples:

# Show matching entities in a space as CSV
uv run ado show entities space space-abc123-456def --include matching \
                                             --property-format target \
                                             -o csv --output-file space-abc123-456def-entities.csv

# Show entities from an operation with specific properties
uv run ado show entities operation randomwalk-0.5.0-123abc \
                  --property my-property-1 \
                  --property my-property-2 \
                  -o csv --output-file randomwalk-0.5.0-123abc.csv

Show Requests

Get measurement requests sent during an operation:

uv run ado show requests operation [RESOURCE_ID] [--use-latest] \
                            [--output | -o <console | csv | json>] \
                            [--output-file <path>] \
                            [--hide <field>]

Example:

uv run ado show requests operation randomwalk-0.5.0-123abc -o csv

Show Results

Get measurement results metadata (valid/invalid status, etc.):

uv run ado show results operation [RESOURCE_ID] [--use-latest] \
                           [--output | -o <console | csv | json>] \
                           [--output-file <path>] \
                           [--hide <field>]

Note: This shows metadata about results (validity, reasons for invalidity), not the actual measurement values.

Example:

uv run ado show results operation randomwalk-0.5.0-123abc -o csv

Getting Schemas

Get JSON schemas for resource types:

uv run ado template $RESOURCETYPE --include-schema

Example:

# Get space template with schema
uv run ado template space --include-schema

# Get operation template with schema for a specific operator
uv run ado template operation --operator-name OPERATOR_NAME --include-schema

Common Patterns

Find operations that finished successfully

uv run ado get operations -q 'status=[{"event": "finished", "exit_state": "success"}]'

Find spaces containing a specific model

uv run ado get spaces -q 'config.entitySpace={"propertyDomain":{"values":["mistral-7b-v0.1"]}}'

Export operation entities to CSV

uv run ado show entities operation OPERATION_ID -o csv --output-file OPERATION_ID_entities.csv

Get all resources related to a space

uv run ado show related space SPACE_ID

Advanced Filtering

The metastore class can provide more powerful querying via scripts. See orchestrator/metastore/sqlstore.py

References

When modifying or creating code while using this skill, follow:

• AGENTS.md
• plugin-development.mdc (if working with plugins)