--- title: "Query existing resources" method: POST path: "/query" tags: ["Declarative Operations"] --- # Query existing resources `POST /query` ## Request - Base URL: `https://replace-with-account.api.decodable.co/v1alpha2` - URL: `https://replace-with-account.api.decodable.co/v1alpha2/query` - Auth: one of: - HTTP bearer - OAuth 2 - Authorization code: `https://auth.decodable.co/authorize?audience=https://api.decodable.co/` - Token URL: `https://auth.decodable.co/oauth/token` - TypeScript: (a function with typed inputs; its response is checked against the schema) See: [`query` command docs](https://docs.decodable.co/declarative/query.html) for usage details. Requires appropriate permissions matching resources involved. See [`query` options reference](https://docs.decodable.co/declarative/query.html#options) for more details on each field in request body YAML object (query specifier). ## Request body `application/x-yaml` - DeclarativeQuerySpecifier: A declarative `query` specifier. See [`query` options reference](https://docs.decodable.co/declarative/query.html#options) for more details. - `operation` 'get' | 'list' | 'activate' | 'deactivate' | 'delete', nullable: Query operation: one of: | operation | description | | --------- | ----------- | | `get`
(_default_) | Fetch all matched resources.
Include associated values in each resource: schema, properties, etc. | | `list` | Fetch all matched resources.
Include only scalar values. This can be faster in some cases. | | `activate` | Activate all matched resources. | | `deactivate` | Deactivate all matched resources. | | `delete` | Delete all matched resources. | - `kinds` string[], nullable: Include in response only resources whose `kind` is one of these values. - `names` string[], nullable: Include in response only resources whose `name` matches one of these values. Values for this option may include the `*` wildcard, which matches any string in a name. For example: `demo_*`. - `ids` string[], nullable: Include in response only resources whose `id` is one of these values. - `resources` object[], nullable: Include in response only resources whose `kind` and `name` equal those in one of these values. Sort response resources to match. - `kind` string, required - `name` string, required - `active` boolean, nullable: When present, include in response: - When `true`: only active resources. - When `false`: only not-active resources. - Only Connection and Pipeline resources. - `stable` boolean, nullable: When present, include in response: - When `true`: only stable resources. - When `false`: only not-stable resources. - Only Connection and Pipeline resources. - `no_status` boolean, nullable: Return resources without `status` section, suitable for export for source control. - `no_spec` boolean, nullable: Return resources without `spec` section. - `keep_ids` boolean, nullable: Return resources with IDs in `metadata` and `spec` sections. - `include_immutables` boolean, nullable: Include in the response built-in immutable resources, such as `_events` and `_metrics` Streams. *Important:* These resources can't be `apply`'d (or otherwise changed). _Not_ appropriate for export to source control or `apply`. - `spec_versions` object, nullable: - key: `kind` value - value: `spec_version` value (per-`kind`) Select the `spec_version` for one or more `kind`s. Allows your custom tooling to choose the contract (object shape) for `spec` sections of resource definition YAML docs in the `query` response. Note that `spec` shapes won't be compatible across `spec_version`s, and `spec_version` is per-`kind`. The _default_ `spec_version` is the latest for each `kind`. - `tag_expression` string, nullable: A SQL-like expression used to query resources by their tags. The expression filters resources based on tag key and value pairs. The expression format is `key=value`, where both the key and value are case-sensitive. Use logical operators like `AND`, `OR`, and parentheses for more complex queries. Tag queries require values to be enclosed in single quotes. For multi-part queries, double-quote the entire expression to avoid issues with process substitution. ## Response `200` A declarative `query` response: zero or more resource definitions, each with this schema. Note that the response will be `application/x-yaml` by default (with one YAML doc per resource definition), but `application/json` may be selected via the `Accept:` request header. - DeclarativeDefinitionWithStatus: The declarative resource definition format. - `kind` 'secret' | 'stream' | 'connection' | 'pipeline', required: The resource `kind`. - `metadata` object, required: Identifying and labeling information for the resource. - `name` string, required - `description` string - `id` string - `tags` object - `spec_version` 'v1', required: The `spec` version for this resource definition. - `spec` union: Resource configuration, per `kind` and `spec_version`. - object, nullable: `kind: secret`, `spec_version: v1`: no `spec`. - object: `kind: stream`, `spec_version: v1`. - `watermark` string: The stream watermark strategy. - `schema` object[]: Record schema. - `name` string: The field name. - `type` string: The field type. - `schema_v2` SchemaV2: Record schema, version 2. - `fields` union[]: The fields in this schema. - union - PhysicalField: A physical field. - … - ComputedField: A computed field. - … - MetadataField: A metadata field. - … - `watermarks` object[]: Watermark expressions for this stream. At this time only one expression is supported. - `name` string - `expression` string - `constraints` object - `primary_key` string[]: Column names to use for primary key. - `properties` object: The stream properties. - `partition_key` string[]: The fields to use to partition data in the stream - object: `kind: connection`, `spec_version: v1`. - `connector` 'astra-streaming' | 'clickhouse' | 'confluent-cloud' | 'datadog' | 'datagen' | 'delta-lake' | 'druid' | 'dynamodb-cdc' | 'elasticsearch' | 'gcp-pubsub' | 'hudi' | 'influxdb' | 'kafka' | 'kinesis' | 'mongodb' | 'mongodb-cdc' | 'ms-sql' | 'mysql-cdc' | 'oracle' | 'oracle-cdc' | 'pinot' | 'polaris' | 'postgres' | 'postgres-cdc' | 'pulsar' | 'redis' | 'redpanda' | 'redshift' | 'rest' | 'rockset' | 's3' | 's3-lambda' | 's3-v2' | 'singlestore-db' | 'snowflake' | 'startree' | 'streamnative' | 'timescale': The connector used by the connection. - `type` 'source' | 'sink': The connection type. - `stream_mappings` object[]: The connection stream mappings. If present, `schema` and `stream_id` must be `null`. - `stream_id` string: An opaque ID, created by Decodable, that uniquely identifies a resource. - `external_resource_specifier` unknown - `stream_id` string: An opaque ID, created by Decodable, that uniquely identifies a resource. - `schema` object[]: Record schema. - `name` string: The field name. - `type` string: The field type. - `schema_v2` SchemaV2: Record schema, version 2. - `fields` union[]: The fields in this schema. - union - PhysicalField: A physical field. - … - ComputedField: A computed field. - … - MetadataField: A metadata field. - … - `watermarks` object[]: Watermark expressions for this stream. At this time only one expression is supported. - `name` string - `expression` string - `constraints` object - `primary_key` string[]: Column names to use for primary key. - `properties` object: The connection properties. - `autoscale_configuration` AutoscaleConfiguration, nullable: The configuration for autoscale conditions. - `pause_conditions` object, nullable: A map of pause conditions and their given setting values. - `resume_conditions` object, nullable: A map of resume conditions and their given setting values. - object: `kind: pipeline`, `spec_version: v1`. SQL pipeline fields only. - `sql` string: The pipeline SQL. - `snapshot_configuration` SnapshotConfiguration: The pipeline snapshot configuration. - `enabled` boolean: Whether or not to take snapshots. - `cron` string: A cron expression for scheduling the snapshot - `retention_period_seconds` number: A retention period for the created snapshots, in seconds. - `autoscale_configuration` AutoscaleConfiguration, nullable: The configuration for autoscale conditions. - `pause_conditions` object, nullable: A map of pause conditions and their given setting values. - `resume_conditions` object, nullable: A map of resume conditions and their given setting values. - `properties` SQLPipelineProperties - `secrets` string[] - object: `kind: pipeline`, `spec_version: v1`. Custom pipeline fields only. - `type` 'JAVA' | 'PYTHON': The type of the custom pipeline. Consumers should be able to gracefully handle new values in future API versions. - `job_file_sha` string: SHA512 hash of the job file. Must reference a file that was previously uploaded using the `/files` endpoints. - `job_arguments` string: Argument string input to the custom pipeline program. - `entry_class` string: Name of the entry class to run for this custom Java-based pipeline (optional). If not present, the class to run must be specified in the file `META-INF/MANIFEST.MF` within the job's JAR file, using the `Main-Class` property key. - `properties` CustomPipelineProperties - `secrets` string[] - `flink_version` string: The Flink version to run this custom pipeline on. - `additional_metrics` string[] - `flink_configuration` object: A key-value pair of additional Flink configuration to apply to the job - `snapshot_configuration` SnapshotConfiguration: The pipeline snapshot configuration. - `enabled` boolean: Whether or not to take snapshots. - `cron` string: A cron expression for scheduling the snapshot - `retention_period_seconds` number: A retention period for the created snapshots, in seconds. - `status` union: Resource status, per `kind` and `spec_version`. - ResourceTimestamps - `create_time` string, date-time: The date and time the resource was created. - `update_time` string, date-time: The date and time the resource was updated. - ResourceTimestamps - `create_time` string, date-time: The date and time the resource was created. - `update_time` string, date-time: The date and time the resource was updated. - object, nullable: the number of tasks used when an object is activated - `last_runtime_error` RuntimeError: The pipeline last runtime error. - `message` string: last runtime error message - `raw_exception` string: raw exception from the underlying system - `timestamp` string, date-time: last runtime error timestamp - `last_activated_time` string, date-time: The date and time this object was last activated. - `target_state` 'RUNNING' | 'STOPPED' - `actual_state` 'UNKNOWN' | 'STARTING' | 'RUNNING' | 'FAILED' | 'FINISHED' | 'STOPPED' | 'PAUSING' | 'PAUSED' - `requested_tasks` integer: the number of tasks to be allocated to an object when it is activated - `actual_tasks` integer: the number of tasks actively in use by an object - `requested_task_size` string, nullable: the task size to be allocated to an object when it is activated - `actual_task_size` string, nullable: the task size actively in use by an object - `create_time` string, date-time: The date and time the resource was created. - `update_time` string, date-time: The date and time the resource was updated. - object, nullable: The latest Flink configurations defined for this job. When this differs from `actual_system_flink_configuration`, restart the job to apply the latest configurations. - `type` 'SQL': The type of the SQL pipeline. - `version` integer: A version number of a resource - `is_latest` boolean: describe if a versioned resource is the latest version - `active_version` integer, nullable: The active version of the pipeline - `latest_version` integer: The latest version of the pipeline - `last_runtime_error` RuntimeError: The pipeline last runtime error. - `message` string: last runtime error message - `raw_exception` string: raw exception from the underlying system - `timestamp` string, date-time: last runtime error timestamp - `last_activated_time` string, date-time: The date and time this object was last activated. - `target_state` 'RUNNING' | 'STOPPED' - `actual_state` 'UNKNOWN' | 'STARTING' | 'RUNNING' | 'FAILED' | 'FINISHED' | 'STOPPED' | 'PAUSING' | 'PAUSED' - `create_time` string, date-time: The date and time the resource was created. - `update_time` string, date-time: The date and time the resource was updated. - `requested_tasks` integer: the number of tasks to be allocated to an object when it is activated - `actual_tasks` integer: the number of tasks actively in use by an object - `requested_task_size` string, nullable: the task size to be allocated to an object when it is activated - `actual_task_size` string, nullable: the task size actively in use by an object - PipelineV1CommonStatus, nullable: The latest Flink configurations defined for this job. When this differs from `actual_system_flink_configuration`, restart the job to apply the latest configurations. - `version` integer: A version number of a resource - `is_latest` boolean: describe if a versioned resource is the latest version - `active_version` integer, nullable: The active version of the pipeline - `latest_version` integer: The latest version of the pipeline - `last_runtime_error` RuntimeError: The pipeline last runtime error. - `message` string: last runtime error message - `raw_exception` string: raw exception from the underlying system - `timestamp` string, date-time: last runtime error timestamp - `last_activated_time` string, date-time: The date and time this object was last activated. - `target_state` 'RUNNING' | 'STOPPED' - `actual_state` 'UNKNOWN' | 'STARTING' | 'RUNNING' | 'FAILED' | 'FINISHED' | 'STOPPED' | 'PAUSING' | 'PAUSED' - `create_time` string, date-time: The date and time the resource was created. - `update_time` string, date-time: The date and time the resource was updated. - `requested_tasks` integer: the number of tasks to be allocated to an object when it is activated - `actual_tasks` integer: the number of tasks actively in use by an object - `requested_task_size` string, nullable: the task size to be allocated to an object when it is activated - `actual_task_size` string, nullable: the task size actively in use by an object ## Other responses - `400`: An invalid request was received. - `403`: Access denied: requesting user lacks a required permission. - `409`: A conflicting resource already exists. - `default`: An error has occurred. --- [API](https://skmtc.dev/decodable/apis/decodable-control-plane.md) - [All operations](https://skmtc.dev/decodable/apis/decodable-control-plane/llms.txt) - [OpenAPI document](https://skmtc.dev/decodable/apis/decodable-control-plane/revisions/9718a3019da8?raw)