Create Data Source

Use this API to create a new data source connection configuration in NineData.

Request URL: /openapi/v1/datasource/create

Request Method: POST

Request Parameters

Parameter	Type	Required	Description	Example
datasourceType	String	Yes	Data source type. Pass one of the enum values in the table below. Availability depends on the data source types enabled in the target NineData environment.	mysql
name	String	Yes	Specify the name of the data source.	Example MongoDB
username	String	Conditional	Database username. The exact requirement depends on the data source type and authentication mode. See Username and Password Requirements.	<username>
password	String	Conditional	Database password. It has the same required conditions as username. See Username and Password Requirements.	<password>
host	String	Yes	Pass an IP address or domain for a standalone data source; for a replica set or sharded cluster, pass host1:port1,host2:port2.	<DB_HOST>
port	Integer	No	Required in standalone mode. Omit it for replica sets or sharded clusters and include port information in host.	27017
envId	String	No	Environment. Call List Environments to get it.	<envId>
regionId	String	No	Region where the data source belongs. Call the List Regions API to get regionId.	<regionId>
networkType	String	No	Connection method. Defaults to public when omitted. Values: public, gateway, private, and ssh.	public
masterName	String	No	Primary node name for a data source with a primary node.	master-1
hostAndPorts	String	No	Comma-separated host:port pairs for multiple nodes, for example, Redis Sentinel or Cluster nodes.	host1:port1,host2:port2
instanceId	String	No	Required when cloudInstanceType=instance.	<instanceId>
instanceType	String	No	Cloud instance type. Values: ECS, EC2, RDS, Express, Polardb, PolardbX, DRDS, TDSQL, GaussDB, DDS, Aurora, Redis, Kafka, Elasticsearch, ADB, Doris, SCS, MongoDB, DocumentDB, Redshift, clickhouse, GaiaDB, GaiaDBX, OceanBase, VectorDB, VastBase, GoldenDB, CloudSQL, AlloyDB, and GoogleCloud.	RDS
cloudInstanceType	String	No	Cloud instance access mode. Values: instance and url.	instance
vendorRegionId	String	No	Cloud vendor region ID.	cn-hangzhou
serverVersion	String	No	Database server version.	8.0
gatewayId	String	No	Pass it when networkType=gateway.	<gatewayId>
tunnelId	String	No	Usually pass it when networkType=private; the current interface does not enforce it.	<tunnelId>
accessId	String	No	Cloud provider access credential ID used for cloud API calls.	<accessId>
env	String	No	Environment identifier selected by the request.	<environment>
sshConfig	Object	No	Required when networkType=ssh to provide SSH connection settings. See SSHConfig structure.	{}
extraConfig	Object	No	Data-source-specific configuration. Put type-specific parameters in this object. See the details below.	{"authDB":"admin"}

Required-parameter rules

The Required column describes the general request requirement. The actual request must also combine fields according to datasourceType, networkType, and the access mode. Send only the fields required by the selected scenario:

Scenario	Required fields or rule
Every create request	datasourceType and name. datasourceType must also be enabled in the target NineData environment.
Connect in standalone mode	host and port are required.
Connect a replica set or sharded cluster	host is required and must contain the nodes and ports in the form host1:port1,host2:port2; omit port.
Omit networkType	The request is processed as public.
networkType=gateway	Pass gatewayId.
networkType=private	Usually pass tunnelId; the current interface does not enforce it, and omission may be processed as a direct connection.
networkType=ssh	sshConfig is required.
cloudInstanceType=instance	instanceId is required.
Use a cloud provider API	Pass accessId for the target cloud environment. For DataHub, the credential's AccessKey and AccessKeySecret are used as the username and password.
Specify an environment or region	Pass envId or regionId. If envId is omitted, env-dev is used by default; validation fails if that environment does not exist.

Do not replace a field that is not required in the selected scenario with an empty string. Put database credentials, SSH credentials, and cloud provider credentials in their corresponding fields; do not mix them.

The supported datasourceType enum values are:

Data source	datasourceType
MySQL	mysql
SQL Server	sqlserver
Oracle	oracle
PostgreSQL	postgresql
ClickHouse	clickhouse
Elasticsearch	elasticsearch
OpenSearch	opensearch
Trino	trino
ShardingJDBC	sharding_jdbc
ShardingProxy	sharding_proxy
Kafka	kafka
Redis	redis
MongoDB	mongodb
Doris	doris
SelectDB	selectdb
StarRocks	starrocks
OceanBase Oracle	oceanbaseoracle
OceanBase MySQL	oceanbasemysql
Amazon Redshift	redshift
Greenplum	greenplum
YMatrix	ymatrix
DB2	db2
SingleStore	singlestore
Klustron	klustron
Kingbase	kingbase
Kingbase Oracle	kingbaseoracle
Dameng	dameng
DWS	dws
Hive	hive
ADB PostgreSQL	adbpostgresql
openGauss	opengauss
GaussDB	gaussdb
PanWeiDB	panweidb
GBase	gbase
GBase 8a	gbase8a
TiDB	tidb
Sybase	sybase
GreatSQL	greatsql
TDSQL MySQL	tdsqlmysql
TDSQL Oracle	tdsqloracle
DataHub	datahub
ElastiCache	elasticache
VectorDB	vectordb
VastBase	vastbase
Lindorm MySQL	lindormmysql
GoldenDB	goldendb
PegaDB	pega
Milvus	milvus
Chroma	chroma
Qdrant	qdrant
Pinecone	pinecone
Weaviate	weaviate
MariaDB	mariadb
PolarDB Oracle	polardboracle
PolarDB-X	polardbx
PolarDB-X Centralized	polardbxcentralized
DRDS	drds
SQL Database	sqldatabase
Memorystore	memorystore
HANA	hana
YashanDB	yashandb
YashanDB MySQL	yashandbmysql
MaxCompute	maxcompute
HaishanDB	haishandb

Available data source types vary by version and deployment environment. The API returns INVALID_PARAMETER when the value is not enabled in the target environment.

Data Source Types and extraConfig Details

datasourceType determines the type-specific fields that can be used in extraConfig. The table lists the mappings confirmed in the reference appendix. A dash (—) means that the type has no type-specific extraConfig fields. Availability depends on the data source types enabled in the target NineData environment.

Data source type (datasourceType)	Type-specific extraConfig fields
MySQL (mysql)	mysqlConnectionType
Oracle (oracle)	serviceName, sid, role
PostgreSQL (postgresql)	authDB, clientTimezone
Kafka (kafka)	kafkaAuthorization
Redis (redis)	redisDeploymentType; masterName is a top-level field for Sentinel mode, not an extraConfig field
MongoDB (mongodb)	mongoDBDeploymentType, authDB, readPreference, serverSelectionTimeoutMS, cluster
Doris (doris), SelectDB (selectdb), StarRocks (starrocks)	dorisUserBeHostPorts
OceanBase Oracle (oceanbaseoracle)	serviceName, sid, sysTenantUsername, sysTenantPassword
OceanBase MySQL (oceanbasemysql)	mysqlConnectionType, sysTenantUsername, sysTenantPassword
Amazon Redshift (redshift)	authDB
Greenplum (greenplum)	authDB
DB2 (db2)	dbName
GaussDB (gaussdb)	gaussDBInstanceType, gaussDBBigVersion
GBase (gbase)	serverName
GBase 8a (gbase8a)	connectionType, host
MariaDB (mariadb)	mysqlConnectionType
PolarDB Oracle (polardboracle)	clientTimezone
PolarDB-X (polardbx)	mysqlConnectionType, clientTimezone
PolarDB-X Centralized (polardbxcentralized)	mysqlConnectionType
DRDS (drds)	mysqlConnectionType
Memorystore (memorystore)	redisDeploymentType
HANA (hana)	databaseName
YashanDB (yashandb)	serviceName, sid
Hive (hive)	hadoopAuthConfig
Other currently supported types	—; pass top-level fields and follow validation in the target environment

Note: In the current environment, the read-only GET /openapi/v1/datasource/list response also returns version- or type-specific fields for some types, such as useCompression, beHostsEnable, and dorisMapping; SSL responses may also contain tlsAllowInvalidCertificates, tlsAllowInvalidHostnames, and tlsInsecure. These are response extensions and are not included in the generic create-request field list. Before sending them to the create API, verify them against the target environment's interface definition.

extraConfig Object Structure

extraConfig is a JSON object. Its keys are case-sensitive. When creating a data source, pass the type-specific fields for the selected datasourceType. Do not put top-level fields, such as the Redis masterName, inside this object by mistake.

Parameter	Type	Required	Description
clientTimezone	String	No	Client time zone, such as +08:00 or -05:00.
mysqlConnectionType	String	No	MySQL connection type. See the table below for values and host formats.
mongoDBDeploymentType	String	No	MongoDB deployment type. Values: standalone, replicaSet, shardedCluster. The default is standalone.
authDB	String	Conditional	MongoDB authentication database; default database for PostgreSQL, Greenplum, and Amazon Redshift. Required when creating MongoDB data sources.
readPreference	String	No	MongoDB read preference. Values: primary, primaryPreferred, secondary, secondaryPreferred, nearest, default.
serverSelectionTimeoutMS	Integer	No	MongoDB server-selection timeout. The default is 10000.
redisDeploymentType	String	No	Redis deployment type. Values: single, sentinel, cluster.
kafkaAuthorization	String	No	Kafka authentication method. Values: PLAINTEXT, SASL/PLAIN, SASL/SCRAM-SHA-256, SASL/SCRAM-SHA-512.
serviceName	String	Conditional	Oracle service name. Use it or sid, but not both.
sid	String	Conditional	Oracle SID. Use it or serviceName, but not both.
role	String	No	Oracle privilege role. Values: SYSDBA, SYSOPER, default.
dbName	String	Yes	DB2 database name.
databaseName	String	No	Database name for data source types that require it in extraConfig.
gaussDBInstanceType	String	No	GaussDB instance type. Values: centralized, distributed.
gaussDBBigVersion	String	No	GaussDB major version. Values: GaussDB 8.x, GaussDB 3.x.
serverName	String	No	GBase server name. The default is gbaseserver.
clientCharset	String	No	Client character set.
connectionType	String	No	GBase 8a connection type. Values: standalone, multi; the legacy value single is also supported. Required for primary/standby mode.
host	String	No	Standby node address for GBase 8a when connectionType=multi; separate multiple addresses with semicolons (;).
sysTenantUsername	String	Conditional	OceanBase system-tenant username.
sysTenantPassword	String	Conditional	OceanBase system-tenant password.
dorisUserBeHostPorts	Array	No	BE node list for Doris, SelectDB, or StarRocks. Each element has the form {"host":"<BE_HOST>","port":"8040"}.
hadoopAuthConfig	Object	Conditional	Hive authentication settings. When authMethod=KERBEROS, pass Kerberos authentication information in this object; top-level username and password can be omitted.
cluster	Object	No	MongoDB cluster topology. It contains clusterId and a required nodeList; see below.

MySQL connection types:

mysqlConnectionType	host format	Description
single	<DB_HOST> plus port	Direct single-node connection (default).
failover	<HOST_1>:<PORT_1>,<HOST_2>:<PORT_2>	MySQL failover connection that switches to an available node.
replication	<HOST_1>:<PORT_1>,<HOST_2>:<PORT_2>	MySQL read/write splitting connection.

Redis and Kafka rules:

• When redisDeploymentType=sentinel, the top-level masterName is required and host contains the Sentinel node list.
• When redisDeploymentType=cluster, host contains the cluster node list and port can be omitted.
• When kafkaAuthorization is SASL/PLAIN, SASL/SCRAM-SHA-256, or SASL/SCRAM-SHA-512, the top-level username and password are the Kafka authentication credentials. You can omit them when the value is PLAINTEXT or is not passed.

extraConfig.cluster Structure

Parameter	Type	Required	Description
clusterId	String	No	Cluster ID.
nodeList	Array	Yes	Cluster node list.

Each nodeList element has the following structure:

Parameter	Type	Required	Description
nodeId	String	No	Node ID.
nodeHost	String	Yes	Node address.
nodePort	Integer	Yes	Node port.
connectHost	String	No	Connectable address. Defaults to nodeHost.
connectPort	Integer	No	Connectable port. Defaults to nodePort.
username	String	No	Node username.

SSHConfig Structure

When networkType=ssh, pass the SSH tunnel settings in the top-level sshConfig object. sshPassword is required when sshAuthType is password; sshPrivateKey is required when sshAuthType is privateKey.

Parameter	Type	Required	Description
sshHost	String	Yes	SSH host.
sshPort	Integer	No	SSH port. The default is 22.
sshUsername	String	Yes	SSH username.
sshAuthType	String	No	SSH authentication method. Values: password, privateKey.
sshPassword	String	Conditional	Required when sshAuthType=password. SSH password.
sshPrivateKey	String	Conditional	Required when sshAuthType=privateKey. SSH private-key content.
sshPrivateKeyFileName	String	No	SSH private-key file name.
sshPassphrase	String	No	SSH private-key passphrase. Leave it empty when the key has no passphrase.
jumpServerList	Array	No	Jump-server list. Each element has the same structure as this object.

SSH private-key authentication example:

{
  "networkType": "ssh",
  "sshConfig": {
    "sshHost": "<SSH_HOST>",
    "sshPort": 22,
    "sshUsername": "<SSH_USERNAME>",
    "sshAuthType": "privateKey",
    "sshPrivateKey": "<SSH_PRIVATE_KEY>",
    "sshPrivateKeyFileName": "id_rsa",
    "sshPassphrase": "<SSH_PASSPHRASE>"
  }
}

Username and Password Requirements

username and password are database or data source credentials. SSH credentials belong in sshConfig. A create request must include them according to the data source type and authentication method:

Scenario	username/password requirement
MySQL, MariaDB, TiDB, OceanBase MySQL, TDSQL MySQL, PolarDB-X, PolarDB-X Centralized, DRDS, SingleStore, GBase 8a, GreatSQL, GoldenDB, Lindorm MySQL, PostgreSQL, Greenplum, Amazon Redshift, SQL Server, Oracle, OceanBase Oracle, Dameng, YashanDB, DB2, HANA, GaussDB, DWS, GBase, Sybase, Doris, SelectDB, StarRocks, Kingbase, Kingbase Oracle	Required when creating the data source.
MongoDB	Required when creating the data source. Set the authentication database with extraConfig.authDB.
Redis, ElastiCache, Memorystore, PegaDB	Required when account authentication is used; omit them when no authentication is configured.
Kafka	Required when kafkaAuthorization is SASL/PLAIN, SASL/SCRAM-SHA-256, or SASL/SCRAM-SHA-512; omit them when it is PLAINTEXT or not passed.
Hive	When hadoopAuthConfig.authMethod=KERBEROS, top-level username and password can be omitted; for other authentication methods, follow the target authentication configuration.
Elasticsearch, ClickHouse, Trino, ShardingJDBC, and similar types	Follow the target data source authentication method; omit them when authentication is disabled.

If the credentials do not satisfy the authentication requirements for the selected data source type, the API may return a parameter-validation error. Do not replace unused credentials with empty strings, and do not put an SSH password in the top-level password field.

MongoDB Standalone extraConfig Parameters

When you create a MongoDB standalone data source, pass the following fields in extraConfig.

Parameter	Type	Required	Description	Example
mongoDBDeploymentType	String	No	MongoDB deployment type. Pass standalone for standalone mode.	standalone
authDB	String	Yes	Authentication database.	admin

Request Example

The examples below use a gateway to access non-public databases. If the target database is reachable directly from the NineData public network, change networkType to public and remove gatewayId. The network type must match the actual address and network configuration.

MongoDB standalone:

{
  "name": "Example MongoDB",
  "username": "<username>",
  "password": "<password>",
  "host": "<DB_HOST>",
  "port": 27017,
  "datasourceType": "mongodb",
  "regionId": "<regionId>",
  "envId": "<envId>",
  "networkType": "gateway",
  "gatewayId": "<gatewayId>",
  "extraConfig": {
    "mongoDBDeploymentType": "standalone",
    "authDB": "admin"
  }
}

MySQL:

{
  "name": "Example MySQL",
  "username": "<username>",
  "password": "<password>",
  "host": "<DB_HOST>",
  "port": 3306,
  "datasourceType": "mysql",
  "regionId": "<regionId>",
  "envId": "<envId>",
  "networkType": "gateway",
  "gatewayId": "<gatewayId>"
}

PostgreSQL:

{
  "name": "Example PostgreSQL",
  "username": "<username>",
  "password": "<password>",
  "host": "<DB_HOST>",
  "port": 5432,
  "datasourceType": "postgresql",
  "regionId": "<regionId>",
  "envId": "<envId>",
  "networkType": "gateway",
  "gatewayId": "<gatewayId>",
  "extraConfig": {
    "authDB": "<DATABASE_NAME>",
    "clientTimezone": "+08:00"
  }
}

Oracle (SERVICE_NAME):

{
  "name": "Example Oracle",
  "username": "<username>",
  "password": "<password>",
  "host": "<DB_HOST>",
  "port": 1521,
  "datasourceType": "oracle",
  "regionId": "<regionId>",
  "envId": "<envId>",
  "networkType": "gateway",
  "gatewayId": "<gatewayId>",
  "extraConfig": {
    "serviceName": "<SERVICE_NAME>"
  }
}

Return Parameters

Parameter	Type	Description	Example
success	Bool	Whether the API call was successful. Return values: true, false.	true
requestId	String	Request ID.	<requestId>
data	Object	Details of the created data source, including data source ID (datasourceId) information.	{"datasourceId":"<datasourceId>"}

Successful Invocation Example

{
  "success": true,
  "requestId": "<requestId>",
  "data": {
    "datasourceId": "<datasourceId>"
  }
}

Result

A successful response returns the created data source ID in data.datasourceId. Use this ID when you query, update, delete, or grant permissions for the data source.