Push Datasets - Datasets PostDatasetInGroup

Service:: Power BI REST APIs

API Version:: v1.0

Creates a new dataset in the specified workspace.

Required Scope

Dataset.ReadWrite.All

Limitations

This API call only supports push datasets. For a complete list of limitations, see Push datasets limitations.

POST https://api.powerbi.com/v1.0/myorg/groups/{groupId}/datasets

With optional parameters:

POST https://api.powerbi.com/v1.0/myorg/groups/{groupId}/datasets?defaultRetentionPolicy={defaultRetentionPolicy}

URI Parameters

Name	In	Required	Type	Description
groupId	path	True	string (uuid)	The workspace ID
defaultRetentionPolicy	query		DefaultRetentionPolicy	The default retention policy

Request Body

Name	Required	Type	Description
name	True	string	The dataset name
tables	True	Table[]	The dataset tables
datasources		Datasource[]	The data sources associated with this dataset
defaultMode		DatasetMode	The dataset mode or type
relationships		Relationship[]	The dataset relationships

Responses

Name	Type	Description
201 Created	Dataset	Created
202 Accepted	Dataset	Accepted

Examples

Push example

Sample request

POST https://api.powerbi.com/v1.0/myorg/groups/f089354e-8366-4e18-aea3-4cb4a3a50b48/datasets?defaultRetentionPolicy=basicFIFO

Request Body

{
  "name": "SalesMarketing",
  "defaultMode": "Push",
  "tables": [
    {
      "name": "Product",
      "columns": [
        {
          "name": "ProductID",
          "dataType": "Int64"
        },
        {
          "name": "Name",
          "dataType": "string"
        },
        {
          "name": "Category",
          "dataType": "string"
        },
        {
          "name": "IsCompete",
          "dataType": "bool"
        },
        {
          "name": "ManufacturedOn",
          "dataType": "DateTime"
        },
        {
          "name": "Sales",
          "dataType": "Int64",
          "formatString": "Currency"
        }
      ]
    }
  ]
}

Sample response

Status code:: 201

{
  "id": "cfafbeb1-8037-4d0c-896e-a46fb27ff229",
  "name": "SalesMarketing",
  "defaultRetentionPolicy": "basicFIFO"
}

Definitions

Name	Description
ASMashupExpression	A dataset table source
Column	A dataset column
CreateDatasetRequest	A Power BI dataset
CrossFilteringBehavior	The filter direction of the relationship
Dataset	A Power BI dataset. The API returns a subset of the following list of dataset properties. The subset depends on the API called, caller permissions, and the availability of the data in the Power BI database.
DatasetMode	The dataset mode or type
DatasetQueryScaleOutSettings	Query scale-out settings of a dataset
DatasetUser	A Power BI user access right entry for a dataset
DatasetUserAccessRight	The access right that the user has for the dataset (permission level)
Datasource	A Power BI data source
DatasourceConnectionDetails	The Power BI data source connection details. See examples in Get Datasources or Get Datasources In Group.
DefaultRetentionPolicy	The default retention policy
DependentDataflow	A Power BI dependent dataflow
Encryption	Encryption information for a dataset
EncryptionStatus	Dataset encryption status
Measure	A Power BI measure
PrincipalType	The principal type
Relationship	A relationship between tables in a dataset
Row	A data row in a dataset
ServicePrincipalProfile	A Power BI service principal profile. Only relevant for Power BI Embedded multi-tenancy solution.
Table	A dataset table

ASMashupExpression

Object

A dataset table source

Name	Type	Description
expression	string	The source expression

Column

Object

A dataset column

Name	Type	Description
dataCategory	string	Optional. The string value to be used for the data category which describes the data within this column.
dataType	string	The column data type
formatString	string	Optional. The format of the column as specified in FORMAT_STRING.
isHidden	boolean	Optional. Whether the column is hidden. The default is `false`.
name	string pattern: ^[\x09\x0A\x0D\x20-\uD7FF\uE000-\uFFFD\u10000-\u10FFFF]+$	The column name
sortByColumn	string	Optional. String name of a column in the same table to be used to order the current column.
summarizeBy	string	Optional. The aggregate function to use for summarizing this column.

CreateDatasetRequest

Object

A Power BI dataset

Name	Type	Description
datasources	Datasource[]	The data sources associated with this dataset
defaultMode	DatasetMode	The dataset mode or type
name	string	The dataset name
relationships	Relationship[]	The dataset relationships
tables	Table[]	The dataset tables

CrossFilteringBehavior

Enumeration

The filter direction of the relationship

Value	Description
OneDirection	For filtering purposes, the filter will be applied on the table where values are being aggregated.
BothDirections	For filtering purposes, both tables are treated as a single table.
Automatic	Cross filtering behavior is automatically defined

Dataset

Object

A Power BI dataset. The API returns a subset of the following list of dataset properties. The subset depends on the API called, caller permissions, and the availability of the data in the Power BI database.

Name	Type	Description
ContentProviderType	string	A deprecated property that should be ignored.
Encryption	Encryption	Dataset encryption information. Only applicable when `$expand` is specified.
IsEffectiveIdentityRequired	boolean	Whether the dataset requires an effective identity, which you must send in a GenerateToken API call.
IsEffectiveIdentityRolesRequired	boolean	Whether row-level security is defined inside the Power BI .pbix file. If so, you must specify a role.
IsInPlaceSharingEnabled	boolean	Whether the dataset can be shared with external users to be consumed in their own tenant
IsOnPremGatewayRequired	boolean	Whether the dataset requires an on-premises data gateway
IsRefreshable	boolean	This field returns `true` when the dataset is either recently refreshed or is configured for automatic refresh, with the connection mode specifically set to 'Import'. The value will return `false` for other connection modes, such as 'DirectQuery' and 'LiveConnection', regardless of whether the dataset is manually refreshed or is set up for automatic refresh.
addRowsAPIEnabled	boolean	Whether the dataset allows adding new rows
configuredBy	string	The dataset owner
createReportEmbedURL	string	The dataset create report embed URL
createdDate	string (date-time)	The dataset creation date and time
description	string	The dataset description
id	string	The dataset ID
name	string	The dataset name
qnaEmbedURL	string	The dataset Q&A embed URL
queryScaleOutSettings	DatasetQueryScaleOutSettings	Query scale-out settings of a dataset
targetStorageMode	string	The dataset storage mode
upstreamDataflows	DependentDataflow[]	The list of all the dataflows this item depends on
users	DatasetUser[]	(Empty value) The dataset user access details. This property will be removed from the payload response in an upcoming release. You can retrieve user information on a Power BI item (such as a report or a dashboard) by using the Get Dataset Users as Admin API, or the PostWorkspaceInfo API with the `getArtifactUsers` parameter.
webUrl	string	The web URL of the dataset

DatasetMode

Enumeration

The dataset mode or type

Value	Description
AsAzure	A dataset with a live connection to Azure Analysis Services
AsOnPrem	A dataset with a live connection to on-premises Azure Analysis Services
Push	A dataset that allows programmatic access for pushing data into Power BI
Streaming	A dataset that supports data streaming. For more information, see Real-time streaming in Power BI.
PushStreaming	A dataset that supports data streaming and allows programmatic access for pushing data into Power BI

DatasetQueryScaleOutSettings

Object

Query scale-out settings of a dataset

Name	Type	Description
autoSyncReadOnlyReplicas	boolean	Whether the dataset automatically syncs read-only replicas
maxReadOnlyReplicas	integer minimum: -1 maximum: 64	Maximum number of read-only replicas for the dataset (0-64, -1 for automatic number of replicas)

DatasetUser

Object

A Power BI user access right entry for a dataset

Name	Type	Description
datasetUserAccessRight	DatasetUserAccessRight	The access right that the user has for the dataset (permission level)
displayName	string	Display name of the principal
emailAddress	string	Email address of the user
graphId	string	Identifier of the principal in Microsoft Graph. Only available for admin APIs.
identifier	string	Identifier of the principal
principalType	PrincipalType	The principal type
profile	ServicePrincipalProfile	A Power BI service principal profile. Only relevant for Power BI Embedded multi-tenancy solution.
userType	string	Type of the user.

DatasetUserAccessRight

Enumeration

The access right that the user has for the dataset (permission level)

Value	Description
None	Removes permission to the content in the dataset
Read	Grants Read access to the content in the dataset
ReadWrite	Grants Read and Write access to the content in the dataset
ReadReshare	Grants Read and Reshare access to the content in the dataset
ReadWriteReshare	Grants Read, Write, and Reshare access to the content in the dataset
ReadExplore	Grants Read and Explore access to the content in the dataset
ReadReshareExplore	Grants Read, Reshare, and Explore access to the content in the dataset
ReadWriteExplore	Grants Read, Write, and Explore access to the content in the dataset
ReadWriteReshareExplore	Grants Read, Write, Reshare, and Explore access to the content in the dataset

Datasource

Object

A Power BI data source

Name	Type	Description
connectionDetails	DatasourceConnectionDetails	The data source connection details
connectionString	string	(Deprecated) The data source connection string. Available only for DirectQuery.
datasourceId	string (uuid)	The bound data source ID, which is empty when not bound to a gateway
datasourceType	string	The data source type
gatewayId	string (uuid)	The bound gateway ID, which is empty when not bound to a gateway. When using a gateway cluster, the gateway ID refers to the primary (first) gateway in the cluster and is similar to the gateway cluster ID.
name	string	(Deprecated) The data source name. Available only for DirectQuery.

DatasourceConnectionDetails

Object

The Power BI data source connection details. See examples in Get Datasources or Get Datasources In Group.

Name	Type	Description
account	string	The connection account
classInfo	string	The connection class information
database	string	The connection database
domain	string	The connection domain
emailAddress	string	The connection email address
kind	string	The connection kind
loginServer	string	The connection login server
path	string	The connection path
server	string	The connection server
url	string	The connection URL

DefaultRetentionPolicy

Enumeration

The default retention policy

Value	Description
None	None
basicFIFO	basicFIFO

DependentDataflow

Object

A Power BI dependent dataflow

Name	Type	Description
groupId	string	The target group ID
targetDataflowId	string	The target dataflow ID

Encryption

Object

Encryption information for a dataset

Name	Type	Description
EncryptionStatus	EncryptionStatus	Dataset encryption status

EncryptionStatus

Enumeration

Dataset encryption status

Value	Description
Unknown	The encryption status is unknown due to dataset corruption
NotSupported	Encryption isn't supported for this dataset
InSyncWithWorkspace	Encryption is supported and is in sync with the encryption settings
NotInSyncWithWorkspace	Encryption is supported but isn't in sync with the encryption settings

Measure

Object

A Power BI measure

Name	Type	Description
description	string	Optional. The measure description.
expression	string	A valid DAX expression
formatString	string	Optional. A string describing how the value should be formatted when it's displayed as specified in FORMAT_STRING.
isHidden	boolean	Optional. Whether the measure is hidden.
name	string pattern: ^[\x09\x0A\x0D\x20-\uD7FF\uE000-\uFFFD\u10000-\u10FFFF]+$	The measure name

PrincipalType

Enumeration

The principal type

Value	Description
None	No principal type. Use for whole organization level access.
User	User principal type
Group	Group principal type
App	Service principal type

Relationship

Object

A relationship between tables in a dataset

Name	Type	Default value	Description
crossFilteringBehavior	CrossFilteringBehavior	OneDirection	The filter direction of the relationship
fromColumn	string pattern: ^[\x09\x0A\x0D\x20-\uD7FF\uE000-\uFFFD\u10000-\u10FFFF]+$		The name of the foreign key column
fromTable	string pattern: ^[\x09\x0A\x0D\x20\x23\x2D\x30-\x39\x40-\x5A\x5E-\x5F\x61-\x7A\x7E-\uD7FF\uE000-\uFFFD\u10000-\u10FFFF]{1,100}$		The name of the foreign key table
name	string pattern: ^[\x09\x0A\x0D\x20\x23\x2D\x30-\x39\x40-\x5A\x5E-\x5F\x61-\x7A\x7E-\uD7FF\uE000-\uFFFD\u10000-\u10FFFF]{1,100}$		The relationship name and identifier
toColumn	string pattern: ^[\x09\x0A\x0D\x20-\uD7FF\uE000-\uFFFD\u10000-\u10FFFF]+$		The name of the primary key column
toTable	string pattern: ^[\x09\x0A\x0D\x20\x23\x2D\x30-\x39\x40-\x5A\x5E-\x5F\x61-\x7A\x7E-\uD7FF\uE000-\uFFFD\u10000-\u10FFFF]{1,100}$		The name of the primary key table

Row

Object

A data row in a dataset

Name	Type	Description
id	string	The unique row ID

ServicePrincipalProfile

Object

A Power BI service principal profile. Only relevant for Power BI Embedded multi-tenancy solution.

Name	Type	Description
displayName	string	The service principal profile name
id	string (uuid)	The service principal profile ID

Table

Object

A dataset table

Name	Type	Description
columns	Column[]	The column schema for this table
description	string	The table description
isHidden	boolean	Optional. Whether this dataset table is hidden.
measures	Measure[]	The measures within this table
name	string pattern: ^[\x09\x0A\x0D\x20\x23\x2D\x30-\x39\x40-\x5A\x5E-\x5F\x61-\x7A\x7E-\uD7FF\uE000-\uFFFD\u10000-\u10FFFF]{1,100}$	The table name
rows	Row[]	The data rows within this table
source	ASMashupExpression[]	The table source

Share via

Push Datasets - Datasets PostDatasetInGroup

Required Scope

Limitations

URI Parameters

Request Body

Responses

Examples

Push example

Sample request

Sample response

Definitions

ASMashupExpression

Column

CreateDatasetRequest

CrossFilteringBehavior

Dataset

DatasetMode

DatasetQueryScaleOutSettings

DatasetUser

DatasetUserAccessRight

Datasource

DatasourceConnectionDetails

DefaultRetentionPolicy

DependentDataflow

Encryption

EncryptionStatus

Measure

PrincipalType

Relationship

Row

ServicePrincipalProfile

Table