Help Center/ DataArts Insight/ API Reference/ Dataset/ Saving or Modifying a Dataset

Updated on 2025-02-25 GMT+08:00

Online Debugging

CLI Examples

View PDF

Saving or Modifying a Dataset

Function

This API is used to save or modify datasets.

URI

POST /v1/{project_id}/datasets/save

**Table 1** URI parameter
Parameter	Mandatory	Type	Description
project_id	Yes	String	Project ID. For how to obtain the project ID, see Obtaining a Project ID.

Request Parameters

**Table 2** Request header parameters
Parameter	Mandatory	Type	Description
X-Workspace-Id	Yes	String	Workspace ID. For how to obtain it, see Obtaining a Workspace ID.
X-Auth-Token	Yes	String	User token. Obtain a user token by calling IAM's "Obtaining a User Token" API. X-Subject-Token in the response header is the desired user token.

**Table 3** Request body parameters
Parameter	Mandatory	Type	Description
id	No	String	Dataset ID.
caption	Yes	String	Semantic name of a dataset.
status	No	String	Dataset status. The value can be 0 or 1.
description	No	String	Dataset description.
ds_id	Yes	String	Data source ID.
ds_name	No	String	Data source name.
ds_type	No	String	Data source type.
table_type	Yes	String	Dataset type. The options include: table: dataset that does not contain custom SQL tables. sql: dataset that contains custom SQL tables.
resource_code	No	String	Dataset resource ID.
physical_schema	Yes	Table 4 object	Physical schema of the dataset.
logical_schema	Yes	Table 6 object	Logical schema of the dataset.

**Table 4** PhysicalOpenApiSchema
Parameter	Mandatory	Type	Description
tables	Yes	Array of Table 5 objects	Physical tables.

**Table 5** DatasetTableOpenApiVO
Parameter	Mandatory	Type	Description
database_name	Yes	String	Database.
is_fact_table	Yes	Boolean	Whether the table is an endpoint table.
schema_name	No	String	Schema.
sql_text	No	String	Query SQL.
table_name	Yes	String	Table name.
table_type	Yes	String	Table type. The options include: table: physical table. sql: custom SQL table.

**Table 6** LogicalSchemaOpenApiVO
Parameter	Mandatory	Type	Description
filed_schema	No	Table 7 object	Field selection information.
variables	No	Array of Table 9 objects	List of SQL variables.
relations	No	Array of Table 10 objects	Physical table relations.

**Table 7** DatasetFieldSchemaOpenApiVO
Parameter	Mandatory	Type	Description
columns	No	Array of Table 8 objects	Field selection list and field name assignment.

**Table 8** ColumnOpenApiVO
Parameter	Mandatory	Type	Description
caption	Yes	String	Field name.
origin_column_name	Yes	String	Physical name of a field, meaning the name in the table.
schema_name	No	String	Field schema.
table_name	Yes	String	Name of the table where the field is.

**Table 9** SqlVariable
Parameter	Mandatory	Type	Description
default_values	No	Array of objects	Default variable value.
format	No	String	Variable format, which is valid only for variables of the date and time type.
name	Yes	String	Variable name.
type	Yes	String	Variable type. The options include STRING, NUMBER, DATE, DATETIME, and TIMESTAMP. Enumerated values: STRING\|NUMBER\|DATE\|DATETIME\|TIMESTAMP
use_scope	Yes	String	Variable scope. The options are dataset and global.

**Table 10** DatasetRelationOpenApiVO
Parameter	Mandatory	Type	Description
source_database_name	Yes	String	Name of the database the source table belongs to.
source_schema	No	String	Name of the schema the source table belongs to.
source_table_name	Yes	String	Source table name.
target_database_name	Yes	String	Name of the database the target table belongs to.
target_schema	No	String	Name of the schema the target table belongs to.
target_table_name	Yes	String	Target table name.
join_type	Yes	String	Join type.
relation	Yes	String	Relation type.
joins	Yes	Array of Table 11 objects	Join key.

**Table 11** DatasetJoinOpenApiVO
Parameter	Mandatory	Type	Description
condition	Yes	String	Join relationship. The default value is equal-to.
source_key	Yes	String	Source table field.
target_key	Yes	String	Target table field.

Response Parameters

Status code: 200

**Table 12** Response body parameters
Parameter	Type	Description
caption	String	Semantic name of a dataset.
domain_id	String	Tenant ID.
ds_id	String	Data source ID.
ds_type	String	Data source type.
id	String	Dataset ID.
logical_schema	Table 13 object	Logical schema of the dataset.
physical_schema	Table 22 object	Physical schema of the dataset.
project_id	String	Project ID.
version	String	Dataset version. The default value is 2.0. The options include 1.0 and 2.0.
workspace_id	String	Workspace ID.
create_date	Long	Creation timestamp.
create_user	String	Creator ID.
create_user_name	String	Creator name.
update_date	Long	Update timestamp.
update_user	String	ID of the user who performs the update.
update_user_name	String	Name of the user who performs the update.
resource_code	String	Dataset resource ID.

**Table 13** LogicalSchema
Parameter	Type	Description
field_schema	Table 14 object	Field schema.
relations	Array of Table 19 objects	Physical table relations.
variables	Array of Table 21 objects	List of SQL variables.

**Table 14** DatasetFieldSchemaVO
Parameter	Type	Description
dimensions	Array of Table 15 objects	Dimensions.
measures	Array of Table 18 objects	Metrics.

**Table 15** DimensionVo
Parameter	Type	Description
caption	String	Semantic name of a dimension.
cube_id	String	ID of the physical table a dimension belongs to.
description	String	Dimension description.
id	String	Dimension ID.
hierarchies	Array of Table 16 objects	Dimension levels.

**Table 16** Hierarchy
Parameter	Type	Description
caption	String	Semantic name of a hierarchical structure.
levels	Array of Table 17 objects	Hierarchy levels.

**Table 17** LevelVO
Parameter	Type	Description
caption	String	Semantic name.
column_formula	String	Level expression.
data_type	String	Field type. The options are STRING, DATE, and DATETIME. Enumerated values: STRING\|DATE\|DATETIME
expansion_type	Integer	Extension field type. The options are 0 (common extension field) and 1 (aggregation extension field).
id	String	ID.
is_expansion	Integer	Whether a field is an extension field. The options are 0 (no) and 1 (yes). Enumerated values: 0 1
level_type	String	Level type.
origin_column_name	String	Original field name.
origin_column_type	String	Original field type.
origin_data_type	String	Data type before conversion. The options are STRING, DATE, and DATETIME. Enumerated values: STRING\|DATE\|DATETIME

**Table 18** MeasureVo
Parameter	Type	Description
caption	String	Semantic name of a metric.
column_formula	String	Field expression of a metric.
cube_id	String	ID of the physical table a field belongs to.
data_type	String	Data type. The options are STRING, NUMBER, DATE, and DATETIME. Enumerated values: STRING\|NUMBER\|DATE\|DATETIME
expansion_type	Integer	Extension field type. The options are 0 (common extension field) and 1 (aggregation extension field).
id	String	Metric ID.
is_expansion	Integer	Whether a field is an extension field. The options are 0 (no) and 1 (yes).
origin_column_name	String	Original field name.
origin_column_type	String	Original field type.
origin_data_type	String	Data type before conversion. The options are STRING, NUMBER, DATE, and DATETIME. Enumerated values: STRING\|NUMBER\|DATE\|DATETIME

**Table 19** DatasetRelationVO
Parameter	Type	Description
join_type	String	Join type. The options are left join, right join, and inner join.
joins	Array of Table 20 objects	Join key.
relation	String	Relation type. The options include one-to-one, one-to-many, and many-to-one.
source	String	Source table ID.
target	String	Target table ID.

**Table 20** DatasetJoinVO
Parameter	Type	Description
condition	String	Relation. The value is equal-to.
source_key	String	Source field ID.
source_type	String	Source field type. The options are dimension and measure.
target_key	String	Target field ID.
target_type	String	Target field type. The options are dimension and measure.

**Table 21** SqlVariable
Parameter	Type	Description
default_values	Array of objects	Default variable value.
format	String	Variable format, which is valid only for variables of the date and time type.
name	String	Variable name.
type	String	Variable type. The options include STRING, NUMBER, DATE, DATETIME, and TIMESTAMP. Enumerated values: STRING\|NUMBER\|DATE\|DATETIME\|TIMESTAMP
use_scope	String	Variable scope. The options are dataset and global.

**Table 22** PhysicalSchema
Parameter	Type	Description
tables	Array of Table 23 objects	Physical tables. Array length: 0 to 2,147,483,647 elements

**Table 23** DatasetTableVO
Parameter	Type	Description
id	String	Table ID.
database_name	String	Database.
schema_name	String	Schema name.
table_name	String	Table name.
table_type	String	Dataset type.
sql_text	String	Query SQL.
is_fact_table	Boolean	Whether the table is an endpoint table.

Example Request

POST https://{endpoint}/v1/{project_id}/datasets/save 
{ 
  "id" : "string", 
  "caption" : "id", 
  "status" : "string", 
  "description" : "string", 
  "ds_id" : "string", 
  "ds_name" : "string", 
  "ds_type" : "string", 
  "table_type" : "table|sql", 
  "resource_code" : "string", 
  "physical_schema" : { 
    "tables" : [ { 
      "database_name" : "db_test", 
      "is_fact_table" : false, 
      "schema_name" : "public", 
      "sql_text" : "SELECT * FROM FACT_GDP", 
      "table_name" : "t_test", 
      "table_type" : "table" 
    } ] 
  }, 
  "logical_schema" : { 
    "field_schema" : { 
      "columns" : [ { 
        "caption" : "age", 
        "origin_column_name" : "age", 
        "schema_name" : "public", 
        "table_name" : "modern_bi_0xxxx1c590b14d9xxxx35227166f7f02" 
      } ] 
    }, 
    "variables" : [ { 
      "default_values" : [ "aaa", "bbb" ], 
      "format" : "yyyy-MM-dd", 
      "name" : "limit", 
      "type" : "STRING", 
      "use_scope" : "dataset" 
    } ], 
    "relations" : [ { 
      "source_database_name" : "string", 
      "source_schema" : "string", 
      "source_table_name" : "string", 
      "target_database_name" : "string", 
      "target_schema" : "string", 
      "target_table_name" : "string", 
      "join_type" : "string", 
      "relation" : "string", 
      "joins" : [ { 
        "condition" : "equal-to", 
        "source_key" : "city", 
        "target_key" : "city" 
      } ] 
    } ] 
  } 
}