Push Datasets - Datasets PostDataset

Creates a new dataset on My 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/datasets
POST https://api.powerbi.com/v1.0/myorg/datasets?defaultRetentionPolicy={defaultRetentionPolicy}

URI Parameters

Name In Required Type Description
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/datasets?defaultRetentionPolicy=basicFIFO
{
  "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

{
  "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

A dataset table source

Name Type Description
expression

string

The source expression

Column

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

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

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

The filter direction of the relationship

Name Type Description
Automatic

string

Cross filtering behavior is automatically defined

BothDirections

string

For filtering purposes, both tables are treated as a single table.

OneDirection

string

For filtering purposes, the filter will be applied on the table where values are being aggregated.

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.

Name Type Description
ContentProviderType

string

The content provider type for the dataset

CreateReportEmbedURL

string

The dataset create report embed URL

CreatedDate

string

The dataset creation date and time

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.

QnaEmbedURL

string

The dataset Q&A embed URL

addRowsAPIEnabled

boolean

Whether the dataset allows adding new rows

configuredBy

string

The dataset owner

description

string

The dataset description

id

string

The dataset ID

name

string

The dataset name

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

The dataset mode or type

Name Type Description
AsAzure

string

A dataset with a live connection to Azure Analysis Services

AsOnPrem

string

A dataset with a live connection to on-premises Azure Analysis Services

Push

string

A dataset that allows programmatic access for pushing data into Power BI

PushStreaming

string

A dataset that supports data streaming and allows programmatic access for pushing data into Power BI

Streaming

string

A dataset that supports data streaming. For more information, see Real-time streaming in Power BI.

DatasetQueryScaleOutSettings

Query scale-out settings of a dataset

Name Type Description
autoSyncReadOnlyReplicas

boolean

Whether the dataset automatically syncs read-only replicas

maxReadOnlyReplicas

integer

Maximum number of read-only replicas for the dataset (0-64, -1 for automatic number of replicas)

DatasetUser

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

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

Name Type Description
None

string

Removes permission to the content in the dataset

Read

string

Grants Read access to the content in the dataset

ReadExplore

string

Grants Read and Explore access to the content in the dataset

ReadReshare

string

Grants Read and Reshare access to the content in the dataset

ReadReshareExplore

string

Grants Read, Reshare, and Explore access to the content in the dataset

ReadWrite

string

Grants Read and Write access to the content in the dataset

ReadWriteExplore

string

Grants Read, Write, and Explore access to the content in the dataset

ReadWriteReshare

string

Grants Read, Write, and Reshare access to the content in the dataset

ReadWriteReshareExplore

string

Grants Read, Write, Reshare, and Explore access to the content in the dataset

Datasource

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

The bound data source ID, which is empty when not bound to a gateway

datasourceType

string

The data source type

gatewayId

string

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

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

The default retention policy

Name Type Description
None

string

None

basicFIFO

string

basicFIFO

DependentDataflow

A Power BI dependent dataflow

Name Type Description
groupId

string

The target group ID

targetDataflowId

string

The target dataflow ID

Encryption

Encryption information for a dataset

Name Type Description
EncryptionStatus

EncryptionStatus

Dataset encryption status

EncryptionStatus

Dataset encryption status

Name Type Description
InSyncWithWorkspace

string

Encryption is supported and is in sync with the encryption settings

NotInSyncWithWorkspace

string

Encryption is supported but isn't in sync with the encryption settings

NotSupported

string

Encryption isn't supported for this dataset

Unknown

string

The encryption status is unknown due to dataset corruption

Measure

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

The measure name

PrincipalType

The principal type

Name Type Description
App

string

Service principal type

Group

string

Group principal type

None

string

No principal type. Use for whole organization level access.

User

string

User principal type

Relationship

A relationship between tables in a dataset

Name Type Default value Description
crossFilteringBehavior

CrossFilteringBehavior

OneDirection

The filter direction of the relationship

fromColumn

string

The name of the foreign key column

fromTable

string

The name of the foreign key table

name

string

The relationship name and identifier

toColumn

string

The name of the primary key column

toTable

string

The name of the primary key table

Row

A data row in a dataset

Name Type Description
id

string

The unique row ID

ServicePrincipalProfile

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

The service principal profile ID

Table

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

The table name

rows

Row[]

The data rows within this table

source

ASMashupExpression[]

The table source