IoTSiteWise / Client / start_search

start_search

IoTSiteWise.Client.start_search(**kwargs)

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.

See also: AWS API Documentation

Request Syntax

response = client.start_search(
    workspaceName='string',
    queryStatement='string',
    clientToken='string',
    searchType='DEEP'|'QUICK',
    searchFilters={
        'timeSeriesIds': [
            'string',
        ],
        'datasetIds': [
            'string',
        ],
        'timeIntervals': [
            {
                'startTime': {
                    'timeInSeconds': 123,
                    'offsetInNanos': 123
                },
                'endTime': {
                    'timeInSeconds': 123,
                    'offsetInNanos': 123
                }
            },
        ]
    },
    groupId='string'
)

Parameters:

• workspaceName (string) –

  [REQUIRED]

  The name of the workspace whose data is searched.

• queryStatement (string) –

  [REQUIRED]

  The natural-language query describing the data to search for.

• clientToken (string) –

  A unique, case-sensitive identifier you provide to ensure the request is idempotent. Repeating a StartSearch call with the same clientToken returns the original search rather than starting a new one. If omitted, the SDK autogenerates one.

  This field is autopopulated if not provided.

• searchType (string) – The search strategy to use. Defaults to QUICK when omitted.

• searchFilters (dict) –

  Optional filters that restrict the search to a subset of the workspace’s data.

  • timeSeriesIds (list) –

    Restricts the search to these time series.

    • (string) –

  • datasetIds (list) –

    Restricts the search to these datasets.

    • (string) – Unique identifier for a dataset (UUID format)

  • timeIntervals (list) –

    Restricts the search to these time intervals.

    • (dict) –

      Contains a time interval with a start time and an end time. Use a time interval to restrict an operation, such as a search, to a specific time range.

      • startTime (dict) – [REQUIRED]

        The start of the time interval.

        • timeInSeconds (integer) – [REQUIRED]

          The timestamp date, in seconds, in the Unix epoch format. Fractional nanosecond data is provided by offsetInNanos.

        • offsetInNanos (integer) –

          The nanosecond offset from timeInSeconds.

      • endTime (dict) – [REQUIRED]

        The end of the time interval.

        • timeInSeconds (integer) – [REQUIRED]

          The timestamp date, in seconds, in the Unix epoch format. Fractional nanosecond data is provided by offsetInNanos.

        • offsetInNanos (integer) –

          The nanosecond offset from timeInSeconds.

• groupId (string) – An optional caller-supplied identifier used to group related searches together.

Return type:

dict

Returns:

Response Syntax

{
    'searchId': 'string',
    'workspaceName': 'string',
    'status': 'QUEUED'|'RUNNING'|'SUCCEEDED'|'FAILED',
    'groupId': 'string'
}

Response Structure

• (dict) –

  Output of the StartSearch operation.

  • searchId (string) –

    The unique identifier assigned to the newly started search.

  • workspaceName (string) –

    The name of the workspace the search runs against.

  • status (string) –

    The initial status of the search. A newly started search is QUEUED.

  • groupId (string) –

    The group identifier associated with the search, if one was supplied on the request.

Exceptions

• IoTSiteWise.Client.exceptions.InternalFailureException

• IoTSiteWise.Client.exceptions.AccessDeniedException

• IoTSiteWise.Client.exceptions.InvalidRequestException

• IoTSiteWise.Client.exceptions.LimitExceededException

• IoTSiteWise.Client.exceptions.ResourceNotFoundException

• IoTSiteWise.Client.exceptions.ThrottlingException

• IoTSiteWise.Client.exceptions.ConflictingOperationException