Data query
This section contains data query proto files.
Notes:
- To download Gatekeeper proto files, click download Gatekeeper proto files.
- Default values are determined by the gRPC specification. For more information, go to protocol buffers language guide .
dataquery/data_query_service.proto
DataQueryManager
This service allows executing custom queries that extract data from the system. The queries are formed using filters that limit the amount of data extracted from the system.
gRPC method definitions
| Method Name | Request Type | Response Type | Description |
|---|---|---|---|
| ExecuteDataQuery | ExecuteDataQuery Request |
ExecuteDataQuery Response |
Executes a data query and returns a unique data query ID that can later be used to monitor the query’s progress and status. Queries are executed one at a time. The data_query_state specifies the query’s progress. |
| GetDataQueryDetails | GetDataQueryDetails Request |
GetDataQueryDetails Response |
Returns the details of the query specified using its unique data query ID. Use fieldmask to select a subset of the results. |
| ListDataQueries | ListDataQueries Request |
ListDataQueries Response |
Lists all data queries. You can filter queries by data_query_state. Use fieldmask to select a subset of the results. |
| DeleteDataQuery | DeleteDataQuery Request |
DeleteDataQuery Response |
Permanently deletes a data query and its results. Aborts the query if it is still running. |
dataquery/data_query_messages.proto
AbsoluteTimeRange
An absolute time range defined using UTC timestamps start time and end time. Both start and end times are inclusive.
| Field | Type | Description |
|---|---|---|
| start_time | google.protobuf.Timestamp | Mandatory. Interval start time. |
| end_time | google.protobuf.Timestamp | Mandatory. Interval end time. |
AggregationFilter
Defines the aggregation filter.
| Field | Type | Description |
|---|---|---|
| One of aggregation: | Mandatory. |
|
| min_person_occurrences | int32 | Defines the minimum number of occurrences of a person in the entire set of engagements. Use this aggregation when the data filter contains the enroll or verify factor type. |
| min_fraudster_occurrences | int32 | Defines the minimum number of occurrences of a fraudster in the entire set of engagements. This aggregation should be used when the data filter contains the detect known fraudster factor type. |
DataFilter
Defines engagement data filters based on rule type. Rule type is used to determine how to group data rule items. For example, if rule_type is equal to RULE_TYPE_OR_OF_ANDS, data rule items are combined using the AND operator within data item groups and the groups themselves are combined using the OR operator. Following are some of the examples:
- [(factor_type = ‘FACTOR_TYPE_ENROLL_VOICEPRINT’ )]
- [(factor_type = ‘FACTOR_TYPE_ENROLL_VOICEPRINT’ AND factor_type = ‘FACTOR_TYPE_VERIFY_VOICEPRINT’)]
- [(tag = ‘TI’ OR tag = ‘TD’)] AND [(factor_type = ‘FACTOR_TYPE_ENROLL_VOICEPRINT’)]
| Field | Type | Description |
|---|---|---|
| rule_type | RuleType | Mandatory. Rule type defining CNF or DNF. |
| data_item_group_rule | repeated DataItemGroupRule | Mandatory. List of data item groups that define this rule. Data item groups are grouped together based on the rule_type field. |
DataItemGroupRule
A group of data items.
| Field | Type | Description |
|---|---|---|
| data_item_rule | repeated DataItemRule | Mandatory. Data items that are grouped together based on the rule_type field. |
DataItemRule
An atomic data item rule.
| Field | Type | Description |
|---|---|---|
| One of rule: | Mandatory. |
|
| factor_type_rule | StringFilterRule | An atomic rule item that defines the filter used on the factor_type field. |
| tag_rule | StringFilterRule | An atomic rule item that defines the filter used on the tag field. |
| configset_rule | StringFilterRule | An atomic rule item that defines the filter used on the configset field. |
| session_type_rule | StringFilterRule | An atomic rule item that defines the filter used on the session_type field. |
| engagement_decision_rule | StringFilterRule | An atomic rule item that defines the filter used on the engagement_decision field. |
| engagement_verdict_rule | StringFilterRule | An atomic rule item that defines the filter used on the engagement_verdict field. |
DataQuery
Defines the data query details.
| Field | Type | Description |
|---|---|---|
| One of query: | Mandatory. The data query, containing filters that define the data that should be extracted. |
|
| tuning_data_query | TuningDataQuery | Defines a way to build the tuning data query. |
DataQueryDetailsForRead
This message is used to return the properties of an existing data query.
| Field | Type | Description |
|---|---|---|
| gk_data_query_id | nuance.biosec.v1.UniqueId | Unique ID of the data query. |
| name | string | Name of the data query. |
| description | string | Description of the data query. |
| data_query | DataQuery | Data query. |
| resource_file_url | string | Location of the output resource file. The URL is set only if the data query state is COMPLETED. |
| expiry_date | google.protobuf.Timestamp | Date and time when the output resource file expires. |
| custom_data | repeated DataQueryDetailsForRead.CustomDataEntry | Custom data in a list of key-value pairs. |
| scheduling | DataQuerySchedulingForRead | Optional. This field specifies when the query is to be executed. |
| output_field_mask | google.protobuf.FieldMask | Optional. Specifies the fields to be included in the output resource file. |
| data_query_state | DataQueryState | Specifies the current state of the job. |
| creation_timestamp | google.protobuf.Timestamp | Date and time when the data query is created. |
| modification_timestamp | google.protobuf.Timestamp | Date and time when the data query is last updated. |
DataQueryDetailsForRead.CustomDataEntry
| Field | Type | Description |
|---|---|---|
| key | string | |
| value | string |
DataQueryDetailsToExecute
Specifies properties of the query that is executed.
| Field | Type | Description |
|---|---|---|
| name | string | Mandatory. Name of the data query. |
| description | string | Optional. Description of the data query. |
| data_query | DataQuery | Mandatory. Data query to be executed. |
| output_field_mask | google.protobuf.FieldMask | Optional. Specifies the fields to be included in the output resource file. |
DataQueryFilter
Data query filter. Allows filtering by state.
| Field | Type | Description |
|---|---|---|
| data_query_state | repeated DataQueryState | Filter by DataQueryState. If not set, the search return queries in any state. |
DataQuerySchedulingForRead
Provides query scheduling information.
| Field | Type | Description |
|---|---|---|
| first_execution_time | google.protobuf.Timestamp | Date and time of the first query execution. |
| recurrence_interval | google.protobuf.Duration | The interval between two executions. if not set, the execution is performed once. |
| last_execution_time | google.protobuf.Timestamp | Date and time of the last execution. |
| next_execution_time | google.protobuf.Timestamp | Date and time of the next execution. |
| last_successful_execution_time | google.protobuf.Timestamp | Date and time of the last successful execution. |
DataQuerySchedulingForWrite
This message is used to configure query scheduling.
| Field | Type | Description |
|---|---|---|
| first_execution_time | google.protobuf.Timestamp | Optional. Date and time of the first query execution. |
| recurrence_interval | google.protobuf.Duration | Optional. The interval between two executions. if not set, the execution is performed once. |
DeleteDataQueryRequest
Input message that defines the parameters for DeleteDataQuery
| Field | Type | Description |
|---|---|---|
| context | nuance.biosec.v1.Context | Mandatory. General request context. |
| gk_data_query_id | nuance.biosec.v1.UniqueId | Mandatory. Unique ID of the data query |
DeleteDataQueryResponse
Output message that defines parameters returned by DeleteDataQuery.
| Field | Type | Description |
|---|---|---|
| status | nuance.rpc.Status | General operation status. |
ExecuteDataQueryRequest
Input message that defines parameters for ExecuteDataQuery.
| Field | Type | Description |
|---|---|---|
| context | nuance.biosec.v1.Context | Mandatory. General request context. |
| details | DataQueryDetailsToExecute | Mandatory. Data query details and properties that the method sets upon creating the data query. |
| scheduling | DataQuerySchedulingForWrite | Mandatory. This field specifies when the query is executed. |
ExecuteDataQueryResponse
Output message that defines parameters returned by ExecuteDataQuery.
| Field | Type | Description |
|---|---|---|
| status | nuance.rpc.Status | General operation status. |
| gk_data_query_id | nuance.biosec.v1.UniqueId | Unique ID of the newly created data query. |
GetDataQueryDetailsRequest
Input message that defines the parameters for GetDataQueryDetails
| Field | Type | Description |
|---|---|---|
| context | nuance.biosec.v1.Context | Mandatory. General request context. |
| gk_data_query_id | nuance.biosec.v1.UniqueId | Mandatory. Unique ID of the newly created query. |
| field_mask | google.protobuf.FieldMask | Optional. A field mask used to specify the DataQueryDetailsForRead fields that the method reads. |
GetDataQueryDetailsResponse
Output message that defines the parameters returned by GetDataQueryDetails.
| Field | Type | Description |
|---|---|---|
| status | nuance.rpc.Status | General operation status. |
| details | DataQueryDetailsForRead | Data query details. |
ListDataQueriesRequest
Input message that defines the parameters for ListDataQueries
| Field | Type | Description |
|---|---|---|
| context | nuance.biosec.v1.Context | Mandatory. General request context. |
| filter | DataQueryFilter | Optional. Filter that limits the list to specific query states. |
| field_mask | google.protobuf.FieldMask | Optional. A field mask used to specify the DataQueryDetailsForRead fields that the method reads. |
ListDataQueriesResponse
Output message that defines the parameters returned by ListDataQueries.
| Field | Type | Description |
|---|---|---|
| status | nuance.rpc.Status | General operation status. |
| details | repeated DataQueryDetailsForRead | Data query details. |
RelativeTimeRange
A relative time range, used mainly to obtain a sliding window. If none are specified, an empty interval is selected.
| Field | Type | Description |
|---|---|---|
| rolling_duration | google.protobuf.Duration | Optional. Duration of time that rolls backward with respect to current time. For example, records from last 7 days. |
StringFilterRule
Defines the simple string filter rules.
| Field | Type | Description |
|---|---|---|
| operator | StringFilterOperator | Mandatory. The string operator that is used to compare the predefined field with the specific value. |
| value | string | Mandatory. The value that is used to compare the predefined field. |
TimeFilter
An absolute time range filter that uses UTC timestamps. The time interval is inclusive of both start time and end time.
| Field | Type | Description |
|---|---|---|
| start_time | google.protobuf.Timestamp | Mandatory. Start time. Extract data starting from this date and time. |
| end_time | google.protobuf.Timestamp | Mandatory. End time. Extract data ending at this date and time. |
| One of time_filter: | Mandatory. Define an absolute time range or a relative time range. |
|
| absolute_filter | AbsoluteTimeRange | Optional. An absolute time range defined using UTC timestamps start time and end time. |
| relative_filter | RelativeTimeRange | Optional. Specifies the relative time elapsed since the moment of the filter execution, such as before X days ago. |
TuningDataFilter
The tuning filter used to extract data.
All tuning data filters are combined using the AND operator.
For Example:
(start_time >= ‘start_time’ AND end_time <= ’end_time’)
AND (factor_type = ‘FACTOR_TYPE_ENROLL_VOICEPRINT’ or factor_type = ‘FACTOR_TYPE_VERIFY’)
AND (count(min_person_occurrence_rule) >= 10)
| Field | Type | Description |
|---|---|---|
| time_filter | TimeFilter | Mandatory. Defines the time interval in which the engagements are created. |
| data_filter | DataFilter | Optional. Defines the filters based on the engagement data such as configsets, profile tag, factor type, and so on. The data filter can be defined as a combination of AND and OR. |
| aggregation_filter | AggregationFilter | Optional. Defines the filter on the overall aggregation of engagements. |
TuningDataQuery
Defines the query, containing filters used to extract the tuning data. The query is applied over all the engagements and its sessions with the specified filters.
| Field | Type | Description |
|---|---|---|
| tuning_data_filter | TuningDataFilter | Mandatory. A filter that limits the list of data items that should be extracted. |
| limit | int32 | Optional. Limits the number of engagement items that are fetched. If not set, all engagements are fetched. |
dataquery/data_query_enums.proto
DataQueryState
Specifies different data query states.
| Name | Number | Description |
|---|---|---|
| DATA_QUERY_STATE_UNSPECIFIED | 0 | Data query state is not specified. Do not use this value. |
| DATA_QUERY_STATE_PENDING | 1 | Data query is created but not started. |
| DATA_QUERY_STATE_STARTED | 2 | Data query started and is in running state. |
| DATA_QUERY_STATE_COMPLETED | 3 | Data query is completed and its results are published. |
| DATA_QUERY_STATE_COMPLETED_NO_DATA_FOUND | 4 | Data query is completed and data is not found. |
| DATA_QUERY_STATE_CANCELLED | 5 | Data query is cancelled. |
| DATA_QUERY_STATE_ERROR | 6 | An error occurred while running the data query. |
RuleType
Rule types.
| Name | Number | Description |
|---|---|---|
| RULE_TYPE_UNSPECIFIED | 0 | Rule type is not specified. Do not use this value. |
| RULE_TYPE_AND_OF_ORS | 1 | Conjunctive normal form. |
| RULE_TYPE_OR_OF_ANDS | 2 | Disjunctive normal form. |
StringFilterOperator
Defines the different types of operators.
| Name | Number | Description |
|---|---|---|
| STRING_FILTER_OPERATOR_UNDEFINED | 0 | String filter is not specified. Do not use this value. |
| STRING_FILTER_OPERATOR_EQUAL_TO | 1 | Compares between two strings. |
| STRING_FILTER_OPERATOR_CONTAINS | 2 | Checks if the string contains the specified substring. |