workspaces

Creates, updates, deletes, gets or lists a workspaces resource.

Overview

Name	workspaces
Type	Resource
Id	aws.iotsitewise.workspaces

Fields

The following fields are returned by SELECT queries:

describe_workspace

Name	Datatype	Description
created_at	string (date-time)	The date the workspace was created, in Unix epoch time.
encryption_configuration	object	The encryption configuration information for the workspace.
updated_at	string (date-time)	The date the workspace was last updated, in Unix epoch time.
workspace_arn	string	The ARN of the workspace. (pattern: <code>^arn:aws(-cn|-us-gov)?:[a-zA-Z0-9-:/_.]+$</code>)
workspace_description	string	The description of the workspace. (pattern: <code>[^\u0000-\u001F\u007F]+</code>)
workspace_name	string	The name of the workspace. (pattern: <code>^[a-zA-Z0-9_-]+$</code>)
workspace_status	object	The status of the workspace, which contains the state and any error message.

list_workspaces

Name	Datatype	Description
name	string	The name of the workspace. (pattern: <code>^[a-zA-Z0-9_-]+$</code>)
arn	string	The ARN of the workspace. (pattern: <code>^arn:aws(-cn|-us-gov)?:[a-zA-Z0-9-:/_.]+$</code>)
created_at	string (date-time)	The date the workspace was created, in Unix epoch time.
status	object	The status of the workspace.
updated_at	string (date-time)	The date the workspace was last updated, in Unix epoch time.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
describe_workspace	select	workspace_name, region		Retrieves information about a workspace.
list_workspaces	select	region	nextToken, maxResults	Retrieves a paginated list of workspaces. Use the nextToken parameter to retrieve additional results.
create_workspace	insert	region, workspaceName, encryptionConfiguration		Creates a workspace in IoT SiteWise. A workspace isolates its resources, such as datasets, time series, pipelines, and tasks, and their data from other workspaces, and has its own quotas and throttling limits. You must specify an encryption configuration when you create a workspace. The operation returns immediately with the workspace in the CREATING state. Provisioning completes asynchronously, after which the workspace state is ACTIVE, or FAILED if provisioning doesn't complete.
update_workspace	update	workspace_name, region		Updates a workspace. You can update only workspaces in the ACTIVE or FAILED state. Fields that you omit from the request are left unchanged. To recover a workspace in the FAILED state, call this operation and supply its encryption configuration again.
delete_workspace	delete	workspace_name, region	clientToken	Deletes a workspace. Before you delete a workspace, you must delete all resources contained in or associated with the workspace, such as datasets, time series, pipelines, and tasks.
batch_associate_data_segments_to_dataset	exec	dataset_id, region, workspaceName, associateDataSegmentEntries		Associates a batch of data segments with a curated dataset. Data segments are time-bounded slices of time series data selected from source session datasets. Data segments that belong to the same time series can't overlap in time, regardless of which dataset they belong to.
batch_disassociate_data_segments_from_dataset	exec	dataset_id, region, workspaceName, disassociateDataSegmentEntries		Disassociates a batch of data segments from a curated dataset. Disassociating a data segment doesn't delete the underlying data in the source session dataset.
cancel_enrichment_job	exec	workspace_name, job_id, region		Cancels a running or pending enrichment job. This is an idempotent operation—calling it multiple times with the same jobId is safe and returns the current status. Behavior Jobs in PENDING or RUNNING status transition to CANCELLED Jobs in RUNNING state may not be cancellable once they have progressed to certain processing stages Jobs already in terminal states (COMPLETED, FAILED, TIMED_OUT) cannot be cancelled; the operation returns a ConflictingOperationException Cancelling an already-CANCELLED job is a no-op and returns the current status (idempotent behavior) The API responds immediately after recording the cancellation Cleanup of job resources happens asynchronously in the background When to Cancel Cancel a job when: The job is taking longer than expected The job was created with incorrect parameters You no longer need the results Idempotency You can safely retry cancellation requests. Calling CancelEnrichmentJob multiple times for the same job returns the current status without error as long as the job is not in a terminal state other than CANCELLED.
cancel_query	exec	workspace_name, query_id, region		Cancels a running query.
start_query	exec	workspace_name, region, queryStatement		Starts an asynchronous SQL query against workspace telemetry, annotations, data segment, and dataset data.
start_search	exec	workspace_name, region, queryStatement		Starts an asynchronous search over the data in a workspace. The search runs in the background; the response returns immediately with a searchId and an initial status of QUEUED. Use DescribeSearch to poll for completion and GetSearchResults to retrieve the results once the search reaches SUCCEEDED. The request is idempotent on clientToken: repeating a call with the same token returns the original search instead of starting a new one.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
dataset_id	string	The ID of the curated dataset to disassociate data segments from.
job_id	string	The unique identifier of the enrichment job to cancel. This is the jobId returned by CreateEnrichmentJob.
query_id	string	The unique identifier for the query execution to cancel.
region	string	AWS region (default: us-east-1)
workspace_name	string	The name of the workspace whose data is searched.
clientToken	string	A unique, case-sensitive identifier that you provide to ensure that the request is idempotent. If you retry a request that completed successfully using the same client token, the retry succeeds without performing any further actions.
maxResults	integer	The maximum number of results to return for each paginated request. Default: 50.
nextToken	string	The token to be used for the next set of paginated results.

SELECT examples

describe_workspace

Retrieves information about a workspace.

SELECT
created_at,
encryption_configuration,
updated_at,
workspace_arn,
workspace_description,
workspace_name,
workspace_status
FROM aws.iotsitewise.workspaces
WHERE workspace_name = '{{ workspace_name }}' -- required
AND region = '{{ region }}' -- required
;

list_workspaces

Retrieves a paginated list of workspaces. Use the nextToken parameter to retrieve additional results.

SELECT
name,
arn,
created_at,
status,
updated_at
FROM aws.iotsitewise.workspaces
WHERE region = '{{ region }}' -- required
AND nextToken = '{{ nextToken }}'
AND maxResults = '{{ maxResults }}'
;

INSERT examples

create_workspace

Creates a workspace in IoT SiteWise. A workspace isolates its resources, such as datasets, time series, pipelines, and tasks, and their data from other workspaces, and has its own quotas and throttling limits. You must specify an encryption configuration when you create a workspace. The operation returns immediately with the workspace in the CREATING state. Provisioning completes asynchronously, after which the workspace state is ACTIVE, or FAILED if provisioning doesn't complete.

INSERT INTO aws.iotsitewise.workspaces (
workspaceName,
workspaceDescription,
encryptionConfiguration,
tags,
clientToken,
region
)
SELECT 
'{{ workspaceName }}' /* required */,
'{{ workspaceDescription }}',
'{{ encryptionConfiguration }}' /* required */,
'{{ tags }}',
'{{ clientToken }}',
'{{ region }}'
RETURNING
workspace_arn,
workspace_name,
workspace_status
;

Manifest

# Description fields are for documentation purposes
- name: workspaces
props:
  - name: region
    value: "{{ region }}"
    description: Required parameter for the workspaces resource.
  - name: workspaceName
    value: "{{ workspaceName }}"
  - name: workspaceDescription
    value: "{{ workspaceDescription }}"
  - name: encryptionConfiguration
    description: |
      Contains the encryption configuration for a workspace.
    value:
      encryptionType: "{{ encryptionType }}"
      kmsKeyId: "{{ kmsKeyId }}"
  - name: tags
    value: "{{ tags }}"
  - name: clientToken
    value: "{{ clientToken }}"

UPDATE examples

update_workspace

Updates a workspace. You can update only workspaces in the ACTIVE or FAILED state. Fields that you omit from the request are left unchanged. To recover a workspace in the FAILED state, call this operation and supply its encryption configuration again.

UPDATE aws.iotsitewise.workspaces
SET 
workspaceDescription = '{{ workspaceDescription }}',
encryptionConfiguration = '{{ encryptionConfiguration }}',
clientToken = '{{ clientToken }}'
WHERE 
workspace_name = '{{ workspace_name }}' --required
AND region = '{{ region }}' --required
RETURNING
workspace_status;

DELETE examples

delete_workspace

Deletes a workspace. Before you delete a workspace, you must delete all resources contained in or associated with the workspace, such as datasets, time series, pipelines, and tasks.

DELETE FROM aws.iotsitewise.workspaces
WHERE workspace_name = '{{ workspace_name }}' --required
AND region = '{{ region }}' --required
AND clientToken = '{{ clientToken }}'
;

Lifecycle Methods

batch_associate_data_segments_to_dataset

Associates a batch of data segments with a curated dataset. Data segments are time-bounded slices of time series data selected from source session datasets. Data segments that belong to the same time series can't overlap in time, regardless of which dataset they belong to.

EXEC aws.iotsitewise.workspaces.batch_associate_data_segments_to_dataset 
@dataset_id='{{ dataset_id }}' --required, 
@region='{{ region }}' --required 
@@json=
'{
"workspaceName": "{{ workspaceName }}", 
"associateDataSegmentEntries": "{{ associateDataSegmentEntries }}", 
"clientToken": "{{ clientToken }}"
}'
;

batch_disassociate_data_segments_from_dataset

Disassociates a batch of data segments from a curated dataset. Disassociating a data segment doesn't delete the underlying data in the source session dataset.

EXEC aws.iotsitewise.workspaces.batch_disassociate_data_segments_from_dataset 
@dataset_id='{{ dataset_id }}' --required, 
@region='{{ region }}' --required 
@@json=
'{
"workspaceName": "{{ workspaceName }}", 
"disassociateDataSegmentEntries": "{{ disassociateDataSegmentEntries }}", 
"clientToken": "{{ clientToken }}"
}'
;

cancel_enrichment_job

Cancels a running or pending enrichment job. This is an idempotent operation—calling it multiple times with the same jobId is safe and returns the current status. Behavior Jobs in PENDING or RUNNING status transition to CANCELLED Jobs in RUNNING state may not be cancellable once they have progressed to certain processing stages Jobs already in terminal states (COMPLETED, FAILED, TIMED_OUT) cannot be cancelled; the operation returns a ConflictingOperationException Cancelling an already-CANCELLED job is a no-op and returns the current status (idempotent behavior) The API responds immediately after recording the cancellation Cleanup of job resources happens asynchronously in the background When to Cancel Cancel a job when: The job is taking longer than expected The job was created with incorrect parameters You no longer need the results Idempotency You can safely retry cancellation requests. Calling CancelEnrichmentJob multiple times for the same job returns the current status without error as long as the job is not in a terminal state other than CANCELLED.

EXEC aws.iotsitewise.workspaces.cancel_enrichment_job 
@workspace_name='{{ workspace_name }}' --required, 
@job_id='{{ job_id }}' --required, 
@region='{{ region }}' --required
;

cancel_query

Cancels a running query.

EXEC aws.iotsitewise.workspaces.cancel_query 
@workspace_name='{{ workspace_name }}' --required, 
@query_id='{{ query_id }}' --required, 
@region='{{ region }}' --required
;

start_query

Starts an asynchronous SQL query against workspace telemetry, annotations, data segment, and dataset data.

EXEC aws.iotsitewise.workspaces.start_query 
@workspace_name='{{ workspace_name }}' --required, 
@region='{{ region }}' --required 
@@json=
'{
"clientToken": "{{ clientToken }}", 
"queryStatement": "{{ queryStatement }}"
}'
;

start_search

Starts an asynchronous search over the data in a workspace. The search runs in the background; the response returns immediately with a searchId and an initial status of QUEUED. Use DescribeSearch to poll for completion and GetSearchResults to retrieve the results once the search reaches SUCCEEDED. The request is idempotent on clientToken: repeating a call with the same token returns the original search instead of starting a new one.

EXEC aws.iotsitewise.workspaces.start_search 
@workspace_name='{{ workspace_name }}' --required, 
@region='{{ region }}' --required 
@@json=
'{
"queryStatement": "{{ queryStatement }}", 
"clientToken": "{{ clientToken }}", 
"searchType": "{{ searchType }}", 
"searchFilters": "{{ searchFilters }}", 
"groupId": "{{ groupId }}"
}'
;