> ## Documentation Index
> Fetch the complete documentation index at: https://docs.siftstack.com/llms.txt
> Use this file to discover all available pages before exploring further.
# calculated_channels
> sift/calculated_channels/v2/calculated_channels.proto
## Services
*RPC methods exposed by this API.*
### CalculatedChannelService
| Method | Request | Response | Description |
| :----------------------------- | :------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------- | :------------------------------------------------------------------------------- |
| GetCalculatedChannel | [GetCalculatedChannelRequest](#getcalculatedchannelrequest) | [GetCalculatedChannelResponse](#getcalculatedchannelresponse) | Retrieve the latest version of a calculated channel |
| CreateCalculatedChannel | [CreateCalculatedChannelRequest](#createcalculatedchannelrequest) | [CreateCalculatedChannelResponse](#createcalculatedchannelresponse) | Create a calculated channel. |
| ListCalculatedChannels | [ListCalculatedChannelsRequest](#listcalculatedchannelsrequest) | [ListCalculatedChannelsResponse](#listcalculatedchannelsresponse) | Retrieve the latest versions of calculated channels based on an optional filter. |
| UpdateCalculatedChannel | [UpdateCalculatedChannelRequest](#updatecalculatedchannelrequest) | [UpdateCalculatedChannelResponse](#updatecalculatedchannelresponse) | Update and create a new version of a calculated channel. |
| ListCalculatedChannelVersions | [ListCalculatedChannelVersionsRequest](#listcalculatedchannelversionsrequest) | [ListCalculatedChannelVersionsResponse](#listcalculatedchannelversionsresponse) | List versions of a particular calculated channel with an optional filter. |
| ResolveCalculatedChannel | [ResolveCalculatedChannelRequest](#resolvecalculatedchannelrequest) | [ResolveCalculatedChannelResponse](#resolvecalculatedchannelresponse) | Resolve a calculated channel into an expression with references. |
| BatchResolveCalculatedChannels | [BatchResolveCalculatedChannelsRequest](#batchresolvecalculatedchannelsrequest) | [BatchResolveCalculatedChannelsResponse](#batchresolvecalculatedchannelsresponse) | Resolve a batch of calculated channels into expressions with references. |
| ListResolvedCalculatedChannels | [ListResolvedCalculatedChannelsRequest](#listresolvedcalculatedchannelsrequest) | [ListResolvedCalculatedChannelsResponse](#listresolvedcalculatedchannelsresponse) | Retrieve the latest versions of calculated channels based on an optional filter. |
| GetCalculatedChannelVersions | [GetCalculatedChannelVersionsRequest](#getcalculatedchannelversionsrequest) | [GetCalculatedChannelVersionsResponse](#getcalculatedchannelversionsresponse) | Retrieve calculated channel versions by their version IDs. |
| GetCalculatedChannelDependents | [GetCalculatedChannelDependentsRequest](#getcalculatedchanneldependentsrequest) | [GetCalculatedChannelDependentsResponse](#getcalculatedchanneldependentsresponse) | Retrieve calculated channels that depend on a given calculated channel. |
## Messages
*Data models used across requests/responses.*
### BatchResolveCalculatedChannelsRequest
The request of a call to `CalculatedChannelService_BatchResolveCalculatedChannels`.
| Field | Type | Label | Description |
| :------- | :------------------------------------------------------------------ | :------- | :---------------------------------- |
| requests | [ResolveCalculatedChannelRequest](#resolvecalculatedchannelrequest) | repeated | All calculated channels to resolve. |
### BatchResolveCalculatedChannelsResponse
The response of a call to `CalculatedChannelService_BatchResolveCalculatedChannels`.
| Field | Type | Label | Description |
| :-------- | :-------------------------------------------------------------------- | :------- | :------------------------------------------------- |
| responses | [ResolveCalculatedChannelResponse](#resolvecalculatedchannelresponse) | repeated | All calculated channels that attempted resolution. |
### CalculatedChannel
| Field | Type | Label | Description |
| :--------------------------------- | :-------------------------------------------------------------------------------- | :------- | :----------------------------------------------------------------------------------------------- |
| calculated\_channel\_id | string | | |
| organization\_id | string | | |
| client\_key | string | optional | |
| archived\_date | google.protobuf.Timestamp | optional | |
| version\_id | string | | |
| version | uint32 | | |
| name | string | | |
| description | string | | |
| change\_message | string | | |
| user\_notes | string | | |
| units | string | optional | |
| created\_date | google.protobuf.Timestamp | | |
| modified\_date | google.protobuf.Timestamp | | |
| calculated\_channel\_configuration | [CalculatedChannelConfiguration](#calculatedchannelconfiguration) | | |
| created\_by\_user\_id | string | | |
| modified\_by\_user\_id | string | | |
| function\_dependencies | [sift.common.type.v1.FunctionDependency](#sift-common-type-v1-functiondependency) | repeated | |
| metadata | [sift.metadata.v1.MetadataValue](#sift-metadata-v1-metadatavalue) | repeated | |
| is\_archived | bool | | Whether the calculated channel is archived. This is inferred from whether archived\_date is set. |
| calculated\_channel\_dependencies | [CalculatedChannelDependency](#calculatedchanneldependency) | repeated | Calculated channels that this channel depends on. |
| folder\_ids | string | repeated | Ids of the folders this calculated channel belongs to. |
### CalculatedChannelAbstractChannelReference
| Field | Type | Label | Description |
| :--------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------- | :---- | :---------------------------------------------------------------------------------- |
| channel\_reference | string | | |
| channel\_identifier | string | | must use either a channel\_identifier or a calculated\_channel\_reference, not both |
| oneof calculated\_channel\_reference. calculated\_channel\_version\_id | string | | |
| oneof calculated\_channel\_reference. calculated\_channel | [sift.calculated\_channels.v1.ExpressionRequest](#sift-calculated_channels-v1-expressionrequest) | | |
### CalculatedChannelAssetConfiguration
| Field | Type | Label | Description |
| :------------------------------ | :-------------------------------------------------------------------------------------------------------- | :---- | :---------- |
| oneof asset\_scope. all\_assets | bool | | |
| oneof asset\_scope. selection | [CalculatedChannelAssetConfiguration.AssetSelection](#calculatedchannelassetconfiguration-assetselection) | | |
### CalculatedChannelAssetConfiguration.AssetSelection
| Field | Type | Label | Description |
| :--------- | :----- | :------- | :---------- |
| asset\_ids | string | repeated | |
| tag\_ids | string | repeated | |
### CalculatedChannelConfiguration
| Field | Type | Label | Description |
| :------------------- | :-------------------------------------------------------------------------- | :---- | :---------- |
| asset\_configuration | [CalculatedChannelAssetConfiguration](#calculatedchannelassetconfiguration) | | |
| query\_configuration | [CalculatedChannelQueryConfiguration](#calculatedchannelqueryconfiguration) | | |
### CalculatedChannelDependency
A dependency on another calculated channel.
| Field | Type | Label | Description |
| :------------------------------- | :----- | :---- | :---------- |
| calculated\_channel\_version\_id | string | | |
### CalculatedChannelQueryConfiguration
| Field | Type | Label | Description |
| :--------------- | :---------------------------------------------------------------------------------- | :---- | :---------- |
| oneof query. sel | [CalculatedChannelQueryConfiguration.Sel](#calculatedchannelqueryconfiguration-sel) | | |
### CalculatedChannelQueryConfiguration.Sel
Sift Expression Language.
| Field | Type | Label | Description |
| :------------------------------ | :-------------------------------------------------------------------------------------- | :------- | :---------- |
| expression | string | | |
| expression\_channel\_references | [CalculatedChannelAbstractChannelReference](#calculatedchannelabstractchannelreference) | repeated | |
### CalculatedChannelResolution
| Field | Type | Label | Description |
| :------------------ | :---------------------------------------------------------- | :------- | :---------------------------------------- |
| calculated\_channel | [CalculatedChannel](#calculatedchannel) | optional | The calculated channel resolved. |
| resolved | [ResolvedCalculatedChannel](#resolvedcalculatedchannel) | repeated | All resolved calculated channels. |
| unresolved | [UnresolvedCalculatedChannel](#unresolvedcalculatedchannel) | repeated | All assets with any issues in resolution. |
### CalculatedChannelValidationResult
| Field | Type | Label | Description |
| :---------------- | :----- | :------- | :---------------------------------------------- |
| asset\_id | string | | |
| asset\_name | string | optional | Only included if asset was named in the request |
| tag\_names | string | repeated | Includes all tags that have this asset |
| missing\_channels | string | repeated | Names of the channels that asset does not have |
### CreateCalculatedChannelRequest
| Field | Type | Label | Description |
| :--------------------------------- | :---------------------------------------------------------------- | :------- | :---------- |
| name | string | | |
| description | string | | |
| user\_notes | string | | |
| units | string | optional | |
| client\_key | string | optional | |
| calculated\_channel\_configuration | [CalculatedChannelConfiguration](#calculatedchannelconfiguration) | | |
| metadata | [sift.metadata.v1.MetadataValue](#sift-metadata-v1-metadatavalue) | repeated | |
### CreateCalculatedChannelResponse
| Field | Type | Label | Description |
| :------------------- | :---------------------------------------------------------------------- | :------- | :---------- |
| calculated\_channel | [CalculatedChannel](#calculatedchannel) | | |
| inapplicable\_assets | [CalculatedChannelValidationResult](#calculatedchannelvalidationresult) | repeated | |
### GetCalculatedChannelDependentsRequest
The request for a call to `CalculatedChannelService_GetCalculatedChannelDependents` to retrieve calculated channels that depend on a given calculated channel.
| Field | Type | Label | Description |
| :---------------------------------------------------------- | :----- | :---- | :---------- |
| oneof calculated\_channel. calculated\_channel\_id | string | | |
| oneof calculated\_channel. calculated\_channel\_version\_id | string | | |
### GetCalculatedChannelDependentsResponse
The response of a call to `CalculatedChannelService_GetCalculatedChannelDependents`.
| Field | Type | Label | Description |
| :------------------- | :---------------------------------------- | :------- | :---------- |
| calculated\_channels | [CalculatedChannel](#calculatedchannel) | repeated | |
| rules | [sift.rules.v1.Rule](#sift-rules-v1-rule) | repeated | |
### GetCalculatedChannelRequest
The request for a call to `CalculatedChannelService_GetCalculatedChannel` to retrieve the latest version of a calculated channel.
If `calculated_channel_id` is provided then all other arguments will be ignored. The argument `calculated_channel_id`
should not be used together with `client_key`. The `organization_id` argument is only required
if using `client_key` and the user belongs to multiple organizations.
| Field | Type | Label | Description |
| :------------------------------- | :----- | :---- | :---------- |
| calculated\_channel\_id | string | | |
| client\_key | string | | |
| organization\_id | string | | |
| calculated\_channel\_version\_id | string | | |
### GetCalculatedChannelResponse
| Field | Type | Label | Description |
| :------------------ | :-------------------------------------- | :---- | :---------- |
| calculated\_channel | [CalculatedChannel](#calculatedchannel) | | |
### GetCalculatedChannelVersionsRequest
The request for a call to `CalculatedChannelService_GetCalculatedChannelVersions` to retrieve versions of calculated channels by their version IDs.
| Field | Type | Label | Description |
| :-------------------------------- | :----- | :------- | :---------- |
| calculated\_channel\_version\_ids | string | repeated | |
### GetCalculatedChannelVersionsResponse
The response of a call to `CalculatedChannelService_GetCalculatedChannelVersions`.
| Field | Type | Label | Description |
| :------------------- | :-------------------------------------- | :------- | :---------- |
| calculated\_channels | [CalculatedChannel](#calculatedchannel) | repeated | |
### ListCalculatedChannelVersionsRequest
The request for a call to `CalculatedChannelService_ListCalculatedChannelVersions` to retrieve versions
of a particular calculated channel. If `calculated_channel_id` is provided then `client_key` is ignored.
| Field | Type | Label | Description |
| :---------------------- | :----- | :---- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| calculated\_channel\_id | string | | |
| client\_key | string | | |
| page\_size | uint32 | | The maximum number of calculated channel versions to return. The service may return fewer than this value. If unspecified, at most 50 calculated channels will be returned. The maximum value is 1000; values above 1000 will be coerced to 1000. Optional. |
| page\_token | string | | A page token, received from a previous `ListCalculatedChannelVersions` call. Provide this to retrieve the subsequent page. When paginating, all other parameters provided to `ListCalculatedChannelVersions` must match the call that provided the page token. Optional. |
| filter | string | | A [Common Expression Language (CEL)](https://github.com/google/cel-spec) filter string. Available fields to filter by are `calculated_channel_id`, `organization_id`, `client_key`, `name`, `description`, `asset_id`, `asset_name`, `tag_id`, `tag_name`, `version`, `units`, `calculated_channel_version_id`, `created_date`, `modified_date`, `created_by_user_id`, `modified_by_user_id`, `is_archived`, and `archived_date`. For further information about how to use CELs, please refer to [this guide](https://github.com/google/cel-spec/blob/master/doc/langdef.md#standard-definitions). For more information about the fields used for filtering, please refer to [this definition](/docs/api/grpc/protocol-buffers/calculated_channels#calculated_channel). Optional. |
| organization\_id | string | | This field is only required if your user belongs to multiple organizations. |
| order\_by | string | | How to order the retrieved calculated channel versions. Formatted as a comma-separated string i.e. "FIELD\_NAME\[ desc],...". Available fields to order\_by are 'version', `created_date`, `modified_date`, `name`, `description`, `units`, and `archived_date`. If left empty, items are ordered by `created_date` in ascending order (oldest-first). For more information about the format of this field, read [this](https://google.aip.dev/132#ordering) Example: "created\_date desc,modified\_date". |
### ListCalculatedChannelVersionsResponse
The response of a call to `CalculatedChannelService_ListCalculatedChannelVersions`.
| Field | Type | Label | Description |
| :---------------------------- | :-------------------------------------- | :------- | :---------- |
| calculated\_channel\_versions | [CalculatedChannel](#calculatedchannel) | repeated | |
| next\_page\_token | string | | |
### ListCalculatedChannelsRequest
The request for a call to `CalculatedChannelService_ListCalculatedChannels` to retrieve latest versions of calculated channels.
| Field | Type | Label | Description |
| :--------------- | :----- | :---- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| page\_size | uint32 | | The maximum number of calculated channels to return. The service may return fewer than this value. If unspecified, at most 50 calculated channels will be returned. The maximum value is 1000; values above 1000 will be coerced to 1000. Optional. |
| page\_token | string | | A page token, received from a previous `ListCalculatedChannels` call. Provide this to retrieve the subsequent page. When paginating, all other parameters provided to `ListCalculatedChannels` must match the call that provided the page token. Optional. |
| filter | string | | A [Common Expression Language (CEL)](https://github.com/google/cel-spec) filter string. Available fields to filter by are `calculated_channel_id`, `organization_id`, `client_key`, `name`, `description`, `asset_id`, `asset_name`, `tag_id`, `tag_name`, `units`, `calculated_channel_version_id`, `created_date`, `modified_date`, `created_by_user_id`, `modified_by_user_id`, `is_archived`, and `archived_date`. Folder membership is filterable via the `folders` and `activeFolders` fields. Both contain the ids of the folders the calculated channel belongs to; `activeFolders` excludes archived folders. Use `"" in folders` to return calculated channels in the given folder, and `size(activeFolders) == 0` to return uncategorized calculated channels (calculated channels whose only memberships are in archived folders count as uncategorized). For further information about how to use CELs, please refer to [this guide](https://github.com/google/cel-spec/blob/master/doc/langdef.md#standard-definitions). For more information about the fields used for filtering, please refer to [this definition](/docs/api/grpc/protocol-buffers/calculated_channels#calculated_channel). Optional. |
| organization\_id | string | | This field is only required if your user belongs to multiple organizations. |
| order\_by | string | | How to order the retrieved calculated channels. Formatted as a comma-separated string i.e. "FIELD\_NAME\[ desc],...". Available fields to order\_by are `created_date`, `modified_date`, `name`, `description`, `units`, and `archived_date`. If left empty, items are ordered by `created_date` in descending order (newest-first). For more information about the format of this field, read [this](https://google.aip.dev/132#ordering) Example: "created\_date desc,modified\_date" |
### ListCalculatedChannelsResponse
The response of a call to `CalculatedChannelService_ListCalculatedChannels`.
| Field | Type | Label | Description |
| :------------------- | :-------------------------------------- | :------- | :---------- |
| calculated\_channels | [CalculatedChannel](#calculatedchannel) | repeated | |
| next\_page\_token | string | | |
### ListResolvedCalculatedChannelsRequest
| Field | Type | Label | Description |
| :---------- | :----- | :---- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| asset\_id | string | | Assets or runs to get the resolved calculated channels for. At least one asset or run must be provided. |
| run\_id | string | | |
| page\_size | uint32 | | The maximum number of calculated channels to return. The service may return fewer than this value. If unspecified, at most 50 calculated channels will be returned. The maximum value is 1000; values above 1000 will be coerced to 1000. Optional. |
| page\_token | string | | A page token, received from a previous `ListCalculatedChannels` call. Provide this to retrieve the subsequent page. When paginating, all other parameters provided to `ListCalculatedChannels` must match the call that provided the page token. Optional. |
| filter | string | | A [Common Expression Language (CEL)](https://github.com/google/cel-spec) filter string. Available fields to filter by are `calculated_channel_id`, `organization_id`, `client_key`, `name`, `description`, `asset_id`, `asset_name`, `tag_id`, `tag_name`, `version`, `units`, `calculated_channel_version_id`, `created_date`, `modified_date`, `created_by_user_id`, `modified_by_user_id`, `is_archived`, and `archived_date`. For further information about how to use CELs, please refer to [this guide](https://github.com/google/cel-spec/blob/master/doc/langdef.md#standard-definitions). For more information about the fields used for filtering, please refer to [this definition](/docs/api/grpc/protocol-buffers/calculated_channels#calculated_channel). Optional. |
| order\_by | string | | How to order the retrieved calculated channels. Formatted as a comma-separated string i.e. "FIELD\_NAME\[ desc],...". Available fields to order\_by are `created_date` and `modified_date`. If left empty, items are ordered by `created_date` in descending order (newest-first). For more information about the format of this field, read [this](https://google.aip.dev/132#ordering) Example: "created\_date desc,modified\_date" |
### ListResolvedCalculatedChannelsResponse
| Field | Type | Label | Description |
| :------------------------------- | :---------------------------------------------------------- | :------- | :---------- |
| calculated\_channel\_resolutions | [CalculatedChannelResolution](#calculatedchannelresolution) | repeated | |
| next\_page\_token | string | | |
### ResolveCalculatedChannelRequest
The request for a call to `CalculatedChannelService_ResolveCalculatedChannel` to get the all possible calculated channels.
1. If the calculated channel has a selection of assets and tags then those assets will be used as a base and then filtered down by the given assets and assets from the run.
2. If the calculated channel is enabled for all assets then:
a) If the request has run and assets from the run will be used as a base and then filtered down by the given assets.
b) If the request has run and no assets then those assets will be used.
c) If the request has only assets then those assets will be used.
The `organization_id` argument is only required if using `client_key` and the user belongs to multiple organizations.
| Field | Type | Label | Description |
| :------------------------------------------------------------ | :-------------------------------------------------------------------------------- | :------- | :-------------------------------------------------------------------------- |
| oneof calculated\_channel. identifier | [sift.common.type.v1.ResourceIdentifier](#sift-common-type-v1-resourceidentifier) | | The calculated channel to resolve. |
| oneof calculated\_channel. calculated\_channel\_configuration | [CalculatedChannelConfiguration](#calculatedchannelconfiguration) | | A configuration for the calculated channel to resolve. |
| organization\_id | string | | This field is only required if your user belongs to multiple organizations. |
| assets | [sift.common.type.v1.NamedResources](#sift-common-type-v1-namedresources) | | Assets to be included or filtered through. See above. |
| run | [sift.common.type.v1.ResourceIdentifier](#sift-common-type-v1-resourceidentifier) | optional | Run to get assets to be included or filtered through. See above. |
### ResolveCalculatedChannelResponse
The response of a call to `CalculatedChannelService_ResolveCalculatedChannel`.
| Field | Type | Label | Description |
| :---------------------- | :---------------------------------------------------------- | :------- | :----------------------------------------------------------- |
| calculated\_channel\_id | string | optional | If provided in the request, the calculated channel resolved. |
| resolved | [ResolvedCalculatedChannel](#resolvedcalculatedchannel) | repeated | All resolved calculated channels. |
| unresolved | [UnresolvedCalculatedChannel](#unresolvedcalculatedchannel) | repeated | All assets with any issues in resolution. |
### ResolvedCalculatedChannel
A specific calculated channel including the asset and exact channels to query.
| Field | Type | Label | Description |
| :------------------ | :----------------------------------------------------------------------------------------------- | :---- | :---------------------------------------------------- |
| asset\_name | string | | The name of the specific asset that was resolved. |
| expression\_request | [sift.calculated\_channels.v1.ExpressionRequest](#sift-calculated_channels-v1-expressionrequest) | | The expression resolved including channel references. |
| output\_data\_type | [sift.common.type.v1.ChannelDataType](#sift-common-type-v1-channeldatatype) | | |
| asset\_id | string | | |
### UnresolvedCalculatedChannel
Any failure in resolution.
| Field | Type | Label | Description |
| :------------- | :----- | :---- | :---------------------------------------------------- |
| asset\_name | string | | The name of the specific asset that was not resolved. |
| error\_message | string | | |
### UpdateCalculatedChannelRequest
The request for a call to `CalculatedChannelService_UpdateCalculatedChannel` to update a calculated channel. Updating a calculated
channel creates a new version of the calculated channel, leaving the previous untouched. If no update is deemed necessary, then the
the current version is returned. To archive calculated channel, specify `archived_date` in the `update mask` as well as a non-null
value for `archived_date` in the `calculated_channel` object. To unarchive a calculated channel, specify `archived_date` in the
`update mask` and a `null` value for `archived_date` in the `calculated_channel` object.
| Field | Type | Label | Description |
| :------------------ | :------------------------------------------------------ | :------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| calculated\_channel | [CalculatedChannel](#calculatedchannel) | | The calculated channel to update. |
| update\_mask | [google.protobuf.FieldMask](#google-protobuf-fieldmask) | | The list of fields to be updated. The fields available to be updated are `name`, `description`, `units`, `metadata`, `query_configuration`, `archived_date`, `is_archived`, and `asset_configuration`. |
| user\_notes | string | optional | Optional user notes to describe changes. |
### UpdateCalculatedChannelResponse
The response of a call to `CalculatedChannelService_UpdateCalculatedChannel`.
| Field | Type | Label | Description |
| :------------------- | :---------------------------------------------------------------------- | :------- | :---------- |
| calculated\_channel | [CalculatedChannel](#calculatedchannel) | | |
| inapplicable\_assets | [CalculatedChannelValidationResult](#calculatedchannelvalidationresult) | repeated | |
## Enums
*Allowed constant values used in message fields.*