Creating and Using Runs

A run represents a discrete time period of data capture from one or more assets. While not mandatory for data ingestion, runs facilitate data identification in Sift and the API. For a formal definition of a run, refer to the protocol buffers documentation.

General Workflow:

1. Create a run
2. Stream data for an asset, including the run ID in each request
3. View the run in Sift

Creating a Run

1. Use the RunService.CreateRun endpoint
2. The response will contain the newly created run details
3. Use the returned run ID when streaming data

Retrieving Runs

Sift provides two methods for retrieving runs:

• RunService.GetRun

  • Requires a specific run ID
  • Useful when the run ID is known

• RunService.ListRuns

  • Allows searching for runs using various criteria
  • Useful when the exact run ID is unknown
  • Search parameters include:
    • client_key
    • name
    • Other fields specified in the ListRunsRequest

Example of querying a run by client_key:

curl -G -H "Authorization: Bearer $API_TOKEN" -d "filter=client_key=='example_client_key'" $SIFT_REST_URL/api/v2/runs

Updating a Run

To update an existing run, use the RunService.UpdateRun endpoint.

Using the Run

There are two primary mechanism to associate run to asset(s) data:

• Manual Association
• Automatic Association

Manual Association

For all data ingestion mechanisms, you can manually provide a run ID.

Example, using ingestion-config-based-streaming:

• Include the run ID in the IngestWithConfigDataStreamRequest
• Use this request with IngestService.IngestWithConfigDataStream
• This ensures the asset data in the request is associated with the specified run

Automatic Association

Use the RunService.CreateAutomaticRunAssociationForAssets endpoint to:

• Associate a run with specific assets in advance
• Assets do not need to exist beforehand

Benefits:

• Data arriving for specified assets automatically associates with the run
• No need to include run ID in each ingestion request

Note: If one of the assets specified has an ongoing run, that is, its stop_time is not set, then the CreateAutomaticRunAssociationForAssets endpoint return an error.