Resources¶

With the ado CLI you work with resources, actuators and operators, and contexts.

Actuators and operators provide capabilities, and resources define how you use them. You store the resources in projects along with the measurement data. To access a particular project you have a context which describes its location and access credentials.

This section covers the different resource types, writing resource definitions, and using the CLI to create resources from the definitions and work with the results.

For more on actuators, operators and contexts see their dedicated sections

• Working with Actuators
• Working with Operators
• Projects & Contexts

Resource Types¶

You use the ado CLI to create, list, inspect, and delete resources. To create a resource, define it in a YAML file and pass it to ado create. The resource definition is then stored in the metastore.

The current ado resources are:

• samplestore: A database for storing entities and measurement results.
• discoveryspace: Describes a set of entities along with the experiment protocols that should be applied to them
• operation: An instance of applying an operator to a discoveryspace. For example, running an optimization
• datacontainer: A collection of string, tabular or location data. Used to store arbitrary output from operations.
• actuatorconfigurations: A configuration for an actuator.
• document: A markdown or HTML report or note stored in the metastore, optionally linked to related resources.

Creating certain resources triggers side effects:

• Creating a samplestore resource creates the underlying tables.
• Creating an operation resource executes the operation, which may sample and measure entities in a space or perform an analysis, potentially producing new resources.

Naming Conventions: Concepts versus Resources¶

ado resources are directly related to ado concepts and usually have the same name. To differentiate a concept and the associated resource in the documentation we adopt the following conventions.

When we refer to concepts, upper case nouns like "Sample Store", "Actuator" are used. However, for the corresponding resources lower case is used, with no spaces, so samplestore and actuator.

Common CLI commands for interacting with resources¶

Here is a list of common ado CLI commands for interacting with resources. See the ado CLI guide for more details

• ado get [resource type]
  • Lists all resources of the requested type
• ado get [resource type] [$identifier] -o yaml
  • Outputs the YAML of resource $identifier
• ado create [resource type] -f [YAMLFILE]
  • Creates the resource of the specified type from the definition in "YAMLFILE"
• ado delete [resource type] [$identifier]
  • Deletes the resource of the specified type with the provided identifier from the database. See the deleting resources section for more information and considerations to keep in mind.
• ado describe [resource type] [$identifier]
  • Outputs a human-readable description of resource $identifier
• ado show related [resource type] [$identifier]
  • List ids of resources related to resource $identifier
• ado template [resource type] --include-schema
  • Outputs a default YAML for the given resource along with a schema file explaining the fields.`

Deleting resources¶

In ado you can delete resources, but there is an important constraint: a resource cannot be deleted if it has dependent (child) resources.

If you attempt to delete a resource that still has children, you will encounter an error similar to the following:

ERROR:  Cannot delete discoveryspace space-3fbaad-c3a5f6 as it has children resources:

                                          IDENTIFIER       TYPE
0  raytune-1.0.2.dev11+1c62218-bayesopt-b7f779  operation

HINT:   You must delete each of them first.

To proceed, ensure that all child resources are deleted (using the ado delete command on them) before attempting to remove the parent resource.

Common features of resources¶

All resources have a YAML or JSON representation which is what is stored in the metastore. The schema of this YAML has a common structure.

config: ... # The configuration of the resource - different for each different type
created: "2024-10-03T12:42:35.786484Z" # Creation date
identifier: space-8f1cfb-91ecfb # Resource identifier
kind: discoveryspace # Resource kind
metadata: {} # Metadata dictionary
provenance: ... # Package provenance frozen at resource creation time
status: [] # A list of status objects describing notable events on the resource
version: v1 # The version of this resource

Resource status¶

The status field of a resource contains an ordered sequence of status updates to it. The most recent update is last. Each status update is associated with an event that occurred to the resource, and this event is captured in the event field. A status update will also have a timestamp, which is when the event was recorded (usually right after it occurred). It can also contain additional event dependent fields.

All resources have status updates recorded for the following events:

• created: When the resource is created
• added: When the resource is added to the metastore
• updated: Whenever the resource is updated in the metastore

Here is an example:

config: ...
created: "2026-07-09T14:35:23.264745Z"
identifier: 88341a
kind: samplestore
metadata: {}
provenance:
  ado:
    distributionName: ado-core
    distributionVersion: 2.0.0
status:
  - event: created
    recorded_at: "2026-07-09T14:35:23.264754Z"
  - event: added
    recorded_at: "2026-07-09T14:35:23.265368Z"
  - event: updated
    recorded_at: "2026-07-24T13:56:36.053942Z"
version: v1

Programmatic view of resources¶

Programmatically each resource type is represented by a Python pydantic model class. All these classes inherit their basic structure from the root resource class ADOResource.

You can load and validate any ado resource YAML with the following code snippet: replace discoveryspace with the name of the resource as shown in above list

import yaml
from ado.core import kindmap

with open("resource.yaml") as f:
    resource = kindmap["discoveryspace"].model_validate(yaml.safe_load(f))

What's next¶