openapi: 3.2.0
info:
title: Visier Data Out Data Query API
description: Visier APIs for getting data out of Visier, such as aggregate data and data version information.
license:
name: Apache License, Version 2.0
url: https://www.apache.org/licenses/LICENSE-2.0
version: 22222222.99201.3040
security:
- ApiKeyAuth: []
BearerAuth: []
- ApiKeyAuth: []
CookieAuth: []
- ApiKeyAuth: []
OAuth2Auth: []
tags:
- name: DataQuery
x-displayName: Data Query
description: Query against your data in Visier to get aggregate and list data.
paths:
/v1/data/query/aggregate:
post:
tags:
- DataQuery
summary: Query aggregate data
description: "To retrieve aggregated values from your data in Visier, you can perform an aggregation. Usually, an aggregation\n retrieves values over a period of time, such as multiple months. You can also group and filter your data in an\n aggregation query to retrieve detailed information."
operationId: DataQuery_Aggregate
parameters:
- name: TargetTenantID
in: header
description: Optionally, specify the tenant that you want to execute the API call on. This defines the tenant that you're logged into. If omitted, the request uses the administrating tenant as the login tenant.
schema:
type: string
- name: ProjectID
in: header
description: Optionally, specify a project in which to make the request. If omitted, the request uses the production version.
schema:
type: string
format: uuid
- name: DataVersionID
in: header
description: Optionally, specify a data version against which to execute the query. If omitted, the request uses the current project's data version or the production version if no project is specified.
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/dataservices.query.AggregationQueryExecutionDTO'
required: true
responses:
default:
description: Default error response
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
'200':
description: Aggregate query response
content:
application/json:
schema:
$ref: '#/components/schemas/dataservices.query.CellSetOrErrorDTO'
application/jsonlines:
schema:
type: string
text/csv:
schema:
type: string
/v1/data/query/connector-version:
get:
tags:
- DataQuery
summary: Retrieve a data out connector's latest version
description: Retrieve the latest released version of a data out connector. Use this endpoint to automate checking connector release versions.
operationId: DataQuery_ConnectorVersion
parameters:
- name: connectorId
in: query
description: "The name of the connector for which to retrieve the latest version. Valid values:\n - `powerbi`: Retrieve the latest version of Visier's Power BI connector.\n - `tableau`: Retrieve the latest version of Visier's Tableau connector."
schema:
enum:
- powerbi
- tableau
type: string
format: enum
responses:
default:
description: Default error response
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/dataservices.query.ConnectorVersionDTO'
security:
- {}
/v1/data/query/list:
post:
tags:
- DataQuery
summary: Query a list of details
description: "To retrieve a list of values for specific objects, you can perform a list query. A list query provides information\n about values for selected data points, and is not an aggregated value. In Visier's interface, a list query is\n comparable to View Details for a specific data point in a visualization."
operationId: DataQuery_List
parameters:
- name: TargetTenantID
in: header
description: Optionally, specify the tenant that you want to execute the API call on. This defines the tenant that you're logged into. If omitted, the request uses the administrating tenant as the login tenant.
schema:
type: string
- name: ProjectID
in: header
description: Optionally, specify a project in which to make the request. If omitted, the request uses the production version.
schema:
type: string
format: uuid
- name: DataVersionID
in: header
description: Optionally, specify a data version against which to execute the query. If omitted, the request uses the data version released by the current project or production version, if no project is specified.
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/dataservices.query.ListQueryExecutionDTO'
required: true
responses:
default:
description: Default error response
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
'200':
description: List query response
content:
application/json:
schema:
$ref: '#/components/schemas/data_out.ListResponse'
application/jsonlines:
schema:
type: string
text/csv:
schema:
type: string
/v1/data/query/snapshot:
post:
tags:
- DataQuery
summary: Query a series of detailed snapshots
description: "To retrieve a collection of `list` query-style snapshots taken at the defined intervals, execute a `snapshot` query.\n Each snapshot in the result is associated with a timestamp, or the \"effective date\" at which date snapshot data was valid.\n This API allows you to request a detailed time series from Visier.\n\n Structurally, a `snapshot` query is similar to a `list` query, but has the following differences:\n * The `snapshot` query may contain a column, `effectiveDateProperty`, that specifies the time for each snapshot. To include the `effectiveDateProperty` column, add the following object to the columns array:\n ```json\n {\n \"columnName\": \"Snapshot_Date\",\n \"columnDefinition\": {\n \"effectiveDateProperty\": {}\n }\n }\n ```\n * The `snapshot` query uses `timeIntervals` (like an `aggregate` query) instead of `timeInterval` (like a `list` query) because the `snapshot` query\n must specify the number of snapshots to generate. To specify the number of snapshots to generate, use the `intervalCount` property in the `timeIntervals` object, as shown next.\n ```json\n {\n \"timeIntervals\": {\n \"fromDateTime\": \"2022-01-01\",\n \"intervalPeriodType\": \"MONTH\",\n \"intervalPeriodCount\": 6,\n \"intervalCount\": 4\n }\n ```"
operationId: Query_Snapshot
parameters:
- name: TargetTenantID
in: header
description: Optionally, specify the tenant that you want to execute the API call on. This defines the tenant that you're logged into. If omitted, the request uses the administrating tenant as the login tenant.
schema:
type: string
- name: ProjectID
in: header
description: Optionally, specify a project in which to make the request. If omitted, the request uses the production version.
schema:
type: string
format: uuid
- name: DataVersionID
in: header
description: Optionally, specify a data version against which to execute the query. If omitted, the request uses the data version released by the current project or production version, if no project is specified.
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/dataservices.query.SnapshotQueryExecutionDTO'
required: true
responses:
default:
description: Default error response
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
'200':
description: List query response
content:
application/json:
schema:
$ref: '#/components/schemas/data_out.ListResponse'
application/jsonlines:
schema:
type: string
text/csv:
schema:
type: string
/v1/data/query/sql:
post:
tags:
- DataQuery
summary: Query aggregate or list data using SQL-like syntax
description: "To retrieve a list of values for specific objects or aggregate values from metrics, you can write queries using SQL-like syntax.\n The response format matches the query type whether aggregate or list. If requested, aggregate query results may be flattened into tabular format.\n\n A SQL-like query is an aggregate if it contains at least one metric. Aggregate queries must specify a time interval divided into periods; for example:\n ```sql\n SELECT\n employeeCount() AS \"Employee Count\",\n level(Gender, \"Gender\") AS Gender\n FROM\n Employee\n WHERE\n Visier_Time IN periods(date(\"2023-01-01\"), 4, period(3, Month));\n ```\n\n A SQL-like query is a list if it does not contain any metrics. List queries define time intervals as simple intervals; for example:\n ```sql\n SELECT\n EmployeeID AS \"Employee ID\",\n level(Gender, \"Gender\") AS Gender\n FROM\n Employee\n WHERE\n Visier_Time BETWEEN date(\"2022-01-01\") AND date(\"2023-01-01\");\n ```"
operationId: DataQuery_SqlLike
parameters:
- name: TargetTenantID
in: header
description: Optionally, specify the tenant that you want to execute the API call on. This defines the tenant that you're logged into. If omitted, the request uses the administrating tenant as the login tenant.
schema:
type: string
- name: ProjectID
in: header
description: Optionally, specify a project in which to make the request. If omitted, the request uses the production version.
schema:
type: string
format: uuid
- name: DataVersionID
in: header
description: Optionally, specify a data version against which to execute the query. If omitted, the request uses the data version released by the current project or production version, if no project is specified.
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/dataservices.query.SqlLikeQueryExecutionDTO'
required: true
responses:
default:
description: Default error response
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
'200':
description: List query response
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/TableResponseDTO'
- $ref: '#/components/schemas/dataservices.query.CellSetDTO'
application/jsonlines:
schema:
type: string
text/csv:
schema:
type: string
components:
schemas:
dataservices.query.QueryExecutionErrorsDTO:
type: object
properties:
errorCode:
type: string
description: A brief identifier of the type of error.
message:
type: string
description: The message of the error.
allErrorDetails:
type: array
items:
$ref: '#/components/schemas/dataservices.query.QueryExecutionErrorDetailsDTO'
description: The list of the error details.
description: The errors that occurred during query execution.
dataservices.query.TimeShiftDTO:
type: object
properties:
periodType:
enum:
- MONTH
- DAY
- WEEK
- QUARTER
- YEAR
type: string
description: The time period type for the shift.
format: enum
periodCount:
type: integer
description: The number of intervals. Default is 1.
format: int32
direction:
enum:
- BACKWARD
- FORWARD
type: string
description: The direction to extend. Default is BACKWARD.
format: enum
description: The amount of time to shift the time interval by, such as backward by one year.
dataservices.query.CellDTO:
type: object
properties:
value:
type: string
description: The value of the cell.
support:
type: string
description: The number of data points contributing to this cell.
coordinates:
type: array
items:
type: integer
format: int32
description: A list of integers representing the coordinates of this cell, identifying its position along each axis.
distribution:
type: array
items:
$ref: '#/components/schemas/dataservices.query.CellDistributionBinDTO'
description: "The optional distribution of this cell.\n This will be populated if distribution calculation is requested, and supported by the query."
description: An individual value in a cell set.
dataservices.query.PlanParameterValueDTO:
type: object
properties:
parameterId:
type: string
description: The unique ID of the plan parameter qualified by the object.
planId:
type: string
description: The unique ID of the plan the parameter is based on.
scenarioId:
type: string
description: The unique ID of the scenario the parameter is based on.
snapshotId:
type: string
description: The unique ID of the snapshot the parameter is based on.
description: The value for a parameter on a planning metric, including the parameter ID and the plan the parameter is based on.
dataservices.query.SnapshotQueryExecutionOptionsDTO:
type: object
properties:
limit:
type: integer
description: "The maximum number of entries to return. Default is to return all entries. If `page` is defined but\n limit is not defined, limit will be set to a default value of 1000."
format: int32
queryMode:
enum:
- DEFAULT
- FILL
- FAIL
type: string
description: Determines how the query should handle column definitions that the query is unable to resolve. Default is DEFAULT.
format: enum
omitHeader:
type: boolean
description: "Option to omit the header from the result.\n If true, queryMode must be either FILL or FAIL.\n Default is false."
calendarType:
enum:
- TENANT_CALENDAR
- GREGORIAN_CALENDAR
type: string
description: "The calendar type to use. This will be used for all time calculations unless explicitly overridden in\n the calculation itself. Default is TENANT_CALENDAR."
format: enum
currencyConversionDate:
type: string
description: The currency conversion date to use. If defined, the currency conversion will use the exchange rates as of this date.
page:
type: integer
description: "A page defines a subset of the overall result set. The number of rows per page is equal to limit\n with the exception of the last page in the result set which may contain fewer rows. `Page` is an index\n that begins at 0. The index to start retrieving results is calculated by multiplying `page` by `limit`."
format: int32
multipleTables:
type: boolean
description: "Option to return multiple table files as zipped archive for derived metrics.\n Default is false. If false, one table is returned for the drill-through metric."
currencyConversionCode:
type: string
description: "The optional target currency for all currency conversions.\n If not specified, the tenant default currency will be used."
dateTimeDisplayMode:
enum:
- EPOCH
- DATETIME
type: string
description: "Control how date-time values are displayed in the result set.\n Supported values:\n * `EPOCH`: The number of elapsed milliseconds since January 1, 1970 in UTC timezone. This is the default.\n * `DATETIME`: The date-time value displayed in `yyyy-MM-dd HH:mm:ssZZ` format."
format: enum
description: A SnapshotQueryExecutionOptions provides additional instructions to perform a snapshot query.
dataservices.query.QueryNumericRangesDTO:
type: object
properties:
property:
allOf:
- $ref: '#/components/schemas/dataservices.query.QueryPropertyDTO'
description: The name and qualifying path of a numeric property. Non-numeric properties are not accepted.
ranges:
type: string
description: The ranges to group data into, expressed as a space-separated string of range-bound values.
includeNegative:
type: boolean
description: If `true`, negative ranges are included. Default is false.
includeIndependentZeroRange:
type: boolean
description: If `true`, 0 is an independent range. Default is false.
includeAllMember:
type: boolean
description: If `true`, a member is included that represents all members on the axis. Default is false.
description: A QueryNumericRanges groups data into specified ranges based on a property value.
dataservices.query.NumericParameterValueDTO:
type: object
properties:
parameterId:
type: string
description: The unique ID of the numeric parameter qualified by the object.
value:
type: number
description: The numeric value of the parameter.
format: double
description: The value of a numeric parameter, including the parameter ID and the numeric value passed into the parameter.
dataservices.query.QueryParameterValueDTO:
type: object
properties:
memberValue:
allOf:
- $ref: '#/components/schemas/dataservices.query.MemberParameterValueDTO'
description: A value for a member parameter.
numericValue:
allOf:
- $ref: '#/components/schemas/dataservices.query.NumericParameterValueDTO'
description: A value for a numeric parameter.
planValue:
allOf:
- $ref: '#/components/schemas/dataservices.query.PlanParameterValueDTO'
description: A value for a plan parameter.
aggregationTypeValue:
allOf:
- $ref: '#/components/schemas/dataservices.query.AggregationTypeParameterValueDTO'
description: A value for an aggregation parameter.
subjectMemberSetValue:
allOf:
- $ref: '#/components/schemas/dataservices.query.SubjectMemberSetParameterValueDTO'
description: A value for a subject member set parameter.
description: An object that contains parameter values for either member or numeric parameters.
dataservices.query.ListQueryExecutionDTO:
type: object
properties:
source:
allOf:
- $ref: '#/components/schemas/dataservices.query.ListQuerySourceDTO'
description: The source data that you want to query.
columns:
type: array
items:
$ref: '#/components/schemas/dataservices.query.PropertyColumnDTO'
description: The columns to include in the result. This must contain at least one column.
sortOptions:
type: array
items:
$ref: '#/components/schemas/dataservices.query.SortOptionDTO'
description: The index and direction to sort a column in the `columns` array.
filters:
type: array
items:
$ref: '#/components/schemas/dataservices.query.QueryFilterDTO'
description: The filters of this query. Omit `filters` if no filtering is required.
timeInterval:
allOf:
- $ref: '#/components/schemas/dataservices.query.QueryTimeIntervalDTO'
description: The time that the data is valid, such as a specific day or period of months.
parameterValues:
type: array
items:
$ref: '#/components/schemas/dataservices.query.QueryParameterValueDTO'
description: The parameter values for either member or numeric parameters.
options:
allOf:
- $ref: '#/components/schemas/dataservices.query.ListQueryExecutionOptionsDTO'
description: Additional instructions for your query, such as a calendar type or conversion information.
description: A ListQueryExecution provides instructions to perform a list query.
TableResponseDTO:
type: object
properties:
header:
type: object
additionalProperties:
type: string
description: Description of the columns in the result set.
rows:
type: array
description: Result rows in key-value format.
items:
type: object
additionalProperties:
type: string
dataservices.query.SubjectMemberSetParameterValueDTO_NamePathDTO:
type: object
properties:
namePath:
type: array
items:
type: string
description: The name path for dimension members.
description: The name path for dimension members.
dataservices.query.SqlLikeQueryExecutionDTO:
type: object
properties:
query:
type: string
description: The SQL-like query string
options:
deprecated: true
allOf:
- $ref: '#/components/schemas/dataservices.query.AggregateQueryExecutionOptionsDTO'
description: "This will be removed as of Spring 2026. Use `aggregateQueryOptions` instead.\n If both `options` and `aggregateQueryOptions` are specified, `aggregateQueryOptions` takes precedence.\n\n Optional aggregate query options.\n **Note**: `enableDescendingSpace` is not supported in SQL-like aggregate queries."
aggregateQueryOptions:
allOf:
- $ref: '#/components/schemas/dataservices.query.AggregateQueryExecutionOptionsDTO'
description: "Options to apply to a SQL-like aggregate query. The query is aggregate if it contains at least one metric.\n **Note**: `enableDescendingSpace` is not supported in SQL-like aggregate queries."
listQueryOptions:
allOf:
- $ref: '#/components/schemas/dataservices.query.ListQueryExecutionOptionsDTO'
description: "Options to apply to a SQL-like list query. The query is list if it contains no metrics and has only properties.\n **Note**: `multipleTables` is not supported in SQL-like list queries."
description: "*\n Request body for SQL-like query executions, which can be either an aggregate or list query.\n For examples that distinguish between aggregate and list queries, see the `POST /v1/data/query/sql` description."
dataservices.query.QueryFilterDTO:
type: object
properties:
formula:
type: string
description: A filter expressed as a formula.
selectionConcept:
allOf:
- $ref: '#/components/schemas/dataservices.datamodel.SelectionConceptReferenceDTO'
description: A filter that uses an existing selection concept in Visier.
memberSet:
allOf:
- $ref: '#/components/schemas/dataservices.query.MemberFilterDTO'
description: A filter that includes or excludes dimension members.
cohort:
allOf:
- $ref: '#/components/schemas/dataservices.query.CohortFilterDTO'
description: A filter that identifies a population at a specific time.
description: A QueryFilter selects specific data points within a population.
dataservices.query.AggregationQuerySourceMetricsDTO:
type: object
properties:
columns:
type: array
items:
$ref: '#/components/schemas/dataservices.query.AggregationQuerySourceMetricDTO'
description: An array of metric columns.
description: "The IDs and column names of multiple metrics.\n\n **Note:**\n Only available when the `Accept` header is `text/csv`."
dataservices.query.QueryDimensionMemberSelectionDTO:
type: object
properties:
dimension:
allOf:
- $ref: '#/components/schemas/dataservices.datamodel.DimensionReferenceDTO'
description: A dimension and its qualifying path to query.
members:
type: array
items:
$ref: '#/components/schemas/dataservices.common.DimensionMemberReferenceDTO'
description: A collection of dimension members to select in the query. This must contain at least one member.
description: A QueryDimensionMemberSelection defines dimension members to select in the query.
dataservices.query.SubjectMemberSetParameterValueDTO_ListOfNamePathDTO:
type: object
properties:
namePaths:
type: array
items:
$ref: '#/components/schemas/dataservices.query.SubjectMemberSetParameterValueDTO_NamePathDTO'
description: The name paths for subject member parameter key values.
description: A list of name paths.
dataservices.query.QueryAxisDTO:
type: object
properties:
formula:
type: string
description: An axis expressed as a formula.
selectionConcept:
allOf:
- $ref: '#/components/schemas/dataservices.datamodel.SelectionConceptReferenceDTO'
description: "An axis that uses an existing selection concept in Visier.\n The resulting axis consists of 3 positions: True, False, and Unknown."
dimensionMemberSelection:
allOf:
- $ref: '#/components/schemas/dataservices.query.QueryDimensionMemberSelectionDTO'
description: An axis that uses existing dimension members in Visier.
memberMapSelection:
allOf:
- $ref: '#/components/schemas/dataservices.query.QueryMemberMapSelectionDTO'
description: An axis that uses an existing member map in Visier.
numericRanges:
allOf:
- $ref: '#/components/schemas/dataservices.query.QueryNumericRangesDTO'
description: An axis that uses an existing range dimension in Visier and defines the ranges to query.
dimensionLevelSelection:
allOf:
- $ref: '#/components/schemas/dataservices.query.QueryDimensionLevelSelectionDTO'
description: An axis that uses levels of existing dimensions in Visier.
dimensionLeafMemberSelection:
allOf:
- $ref: '#/components/schemas/dataservices.query.QueryDimensionLeafSelectionDTO'
description: An axis comprised of all non-data leaf members of an existing dimension in Visier.
dimensionDataMemberSelection:
allOf:
- $ref: '#/components/schemas/dataservices.query.QueryDimensionDataMemberSelectionDTO'
description: An axis comprised of all leaf, including data, members of an existing dimension in Visier.
dimensionLevelWithUncategorizedValueSelection:
allOf:
- $ref: '#/components/schemas/dataservices.query.QueryDimensionLevelSelectionDTO'
description: An axis that uses existing dimension levels in Visier, including uncategorized levels.
tableAxisOptions:
allOf:
- $ref: '#/components/schemas/dataservices.query.QueryAxisOptionsDTO'
description: Additional transformations to perform on this axis. Only available when the Accept header is a table format, such as text/csv or application/jsonlines.
sortAndLimitOptions:
allOf:
- $ref: '#/components/schemas/dataservices.query.QueryAxisSortAndLimitOptionsDTO'
description: Optional sorting and limits to apply to the axis.
description: An axis of a query used to group data points.
dataservices.query.QueryMemberMapPropertyDTO:
type: object
properties:
memberMap:
allOf:
- $ref: '#/components/schemas/dataservices.datamodel.DimensionReferenceDTO'
description: A member map and its qualifying path to query.
targetDimensionName:
type: string
description: The name of the member map's dimension that you want to query. The member selection is based on this dimension.
description: A QueryMemberMapProperty defines an existing member map and its dimension to query.
data_out.ListResponse:
type: object
properties:
header:
$ref: '#/components/schemas/google.protobuf.Any'
rows:
type: array
items:
$ref: '#/components/schemas/google.protobuf.Any'
dataservices.query.QueryMemberMapSelectionDTO:
type: object
properties:
memberMap:
allOf:
- $ref: '#/components/schemas/dataservices.datamodel.DimensionReferenceDTO'
description: A member map and its qualifying path to query.
targetDimensionName:
type: string
description: The name of the member map's dimension that you want to query. The member selection is based on this dimension.
members:
type: array
items:
$ref: '#/components/schemas/dataservices.common.DimensionMemberReferenceDTO'
description: A collection of the selected dimension members from the `targetDimension`. This must contain at least one member.
description: "A QueryMemberMapSelection groups data in a query by dimension members in a member map.\n This allows grouping by a dimension that isn't typically valid on the analytic object being\n queried by selecting a valid member map on the analytic object.\n Note: This is unique to the data query API and cannot be reproduced in Visier's interface."
dataservices.query.QueryDimensionLeafSelectionDTO:
type: object
properties:
dimension:
allOf:
- $ref: '#/components/schemas/dataservices.datamodel.DimensionReferenceDTO'
description: A dimension and its qualifying path to query.
description: "A QueryDimensionLeafSelection allows you to define a member set consisting exclusively\n of leaf-level members for the given dimension. Leaf members are those members that have\n no descendents. A member may be a leaf member regardless of the level it is positioned at.\n This member selection option, excludes data members."
dataservices.query.PropertyColumnDTO:
type: object
properties:
columnName:
type: string
description: "The name of the column. This is optional.\n If not specified, the name of the property is used, or a generic column name if the property is unnamed."
columnDefinition:
allOf:
- $ref: '#/components/schemas/dataservices.query.QueryPropertyDTO'
description: The definition of the property to query on.
description: A named, result column of a list query.
dataservices.query.QueryExecutionErrorDTO:
type: object
properties:
errorCode:
type: string
description: A brief identifier of the type of error.
message:
type: string
description: The details of the error.
allErrors:
type: array
items:
$ref: '#/components/schemas/dataservices.query.QueryExecutionErrorsDTO'
description: All errors
description: "An error that occurred during quer
# --- truncated at 32 KB (98 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/visier/refs/heads/main/openapi/visier-dataquery-api-openapi.yml