Introduction to the import API-Graph Database(Graph Database)-阿里云帮助中心

Send requests to the <gdb-endpoint>:<port>/loader endpoint to import data files from an Object Storage Service (OSS) bucket to a Graph Database (GDB) instance. You can also view the status of import tasks and delete them. This topic provides examples of how to add an import task (POST), view the status of an import task (GET), and delete an import task (DELETE).

Prerequisites

A Graph Database (GDB) instance is created. For more information, see Create an instance.
Note
If you create the bucket in the Object Storage Service (OSS) console, ensure that the GDB instance and the bucket are in the same region.
The data files are uploaded to the bucket. For more information, see Upload data files using the OSS console or Upload data files using ossutil.

Add an import task

You can send an HTTP POST request to the <gdb-endpoint>:<port>/loader endpoint to import data from an OSS bucket to a GDB instance.

Important

The Multipurpose Internet Mail Extensions (MIME) type must be application/json.

Request syntax

{   
   "source" : "${OSS-Path}",  
   "format" : "csv",  
   "ramRoleArn" : "string",  
   "accessKey" : "string",  
   "secretKey" : "string", 
   "mode": "NEW|RESUME|AUTO",  
   "failOnError" : "TRUE/FALSE", 
   "parallelism" : "HIGH/MEDIUM/LOW"
}

Request parameters

Parameter	Type	Description
`source`	string	The URI of the folder in the OSS bucket where the data files are stored. The URI can point to a single file or a folder. If you specify a folder, the GDB instance loads each data file in the folder but does not include files in subfolders. The folder can contain multiple vertex files and multiple edge files. During the loading process, vertex files are loaded first. Edge files and non-vertex files are automatically skipped. The URI can be in one of the following formats: (Recommended) oss://<bucket-name>/<object-key-name> http://<endpoint-name>/<bucket-name>/<object-key-name> Note `<bucket-name>`: Replace this with the name of your bucket. `<object-key-name>`: Replace this with the name of your data file. `<endpoint-name>`: Replace this with the service endpoint that corresponds to the region where your bucket is located. Make sure that the GDB instance and the bucket are in the same region.
`format`	string	The value is fixed to csv.
`ramRoleArn`	string	Replace this with the Alibaba Cloud Resource Name (ARN) information for the authorization to import data files into the bucket. For more information about how to view the ARN, see One-click authorization in the GDB console. Note When you use the `ramRoleArn` method to import data, the import task is limited by the validity period of the Security Token Service (STS) token, which cannot exceed 10 hours. If the task exceeds this limit, it is interrupted, which means the data cannot be fully imported. To import a large volume of data, use the `accessKey` or `secretKey` method.
`accessKey`	string	Replace this with the AccessKey ID of your Alibaba Cloud account. For more information about how to view the AccessKey ID, see Grant permissions using the RAM console. Note You only need to configure either the `accessKey` or the `secretKey` parameter.
`secretKey`	string	Replace this with the AccessKey secret of your Alibaba Cloud account. For more information about how to view the AccessKey secret, see Grant permissions using the RAM console. Note You only need to configure either the `accessKey` or the `secretKey` parameter.
`mode`	string	The loading task mode. Valid values: NEW: Creates a new loading task. This mode can be used to reload data after GDB purges old data. RESUME: Checks whether the current loading task already exists in the system. The task is identified by the `source` parameter. If the task exists and is terminated, the system automatically resumes loading. If the task does not exist, loading stops. Important The loader avoids reloading successfully completed tasks and only attempts to process failed files. The RESUME mode is not currently supported. You cannot resume failed loading tasks. AUTO: Checks whether an identical loading task exists. If one is found, it resumes loading, similar to the RESUME mode. If no identical loading task exists, it creates a new one, similar to the NEW mode. Default: AUTO
`failOnError`	string	Specifies whether the loading task stops completely when an error occurs. Valid values: TRUE: The task stops completely. However, the data loaded before the error occurred still exists. FALSE: The task does not stop completely. The loader attempts to load all data and skips entries that cause errors. Important If this parameter is set to FALSE, the loader attempts to load each parsed record. If a vertex or edge corresponding to the record `id` exists, the loader attempts to update its properties. Default: FALSE
`parallelism`	string	The number of concurrent loading tasks. Valid values: Note You must upgrade your GDB instance to V1.0.20 or later to use this option. This parameter limits the system resources that loading tasks occupy, which can reduce the impact on online requests during data loading. HIGH: The number of concurrent tasks on the loader is twice the number of CPU cores of the instance. MEDIUM: The number of concurrent tasks on the loader is equal to the number of CPU cores of the instance. LOW: The number of concurrent tasks on the loader is half the number of CPU cores of the instance. Default: HIGH

Response syntax
```
{    
   "status" : "200 OK",   
   "payload" : { 
          "loadId" : "<loaderId>"   
    }
}
```
If the query is successful, "200 OK" is returned. For information about other error responses, see List of error messages.
Note
- <loaderId>: The ID of the current import task.
- If an error occurs, a JSON object is returned in the response body. The message object contains a description of the error.

View an import task

You can send an HTTP GET request to the <gdb-endpoint>:<port>/loader endpoint to view the status of an import task.

Note

To view the status of a specific import task, you must include <loaderId> as a URL parameter. You can also append <loaderId> to the URL path.

Request syntax
```
# View import tasks
GET <gdb-endpoint>:<port>/loader

# View a specific import task
# Method 1:
GET <gdb-endpoint>:<port>/loader/<loaderId>
# Method 2:
GET <gdb-endpoint>:<port>/loader?loaderId=<loaderId>
```
Note
- <gdb-endpoint>: The endpoint (internal or public) of the target GDB instance.
- <port>: The port (internal or public) that corresponds to the endpoint of the target GDB instance.
- <loaderId>: The ID of a specific task. If you do not specify this parameter, a list of all loading task IDs is returned.

Response syntax

{  
    "payload":{
        "datatypeMismatchErrors": long,    
        "errors":[],    
        "fullUri": "${OSS-Path}",    
        "insertErrors": long,    
        "loaderId": "${loaderId}",   
        "parsingErrors": long,    
"retryNumber": long,    
        "runNumber": long,    
        "status": "LOAD_COMPLETED",    
        "totalDuplicates": long,   
        "totalRecords": long,   
        "totalTimeSpent": long  
         }, 
        "status": "200 OK"
}

Response parameters

Parameter	Type	Description
`fullUri`	string	The URI of the loaded file.
`runNumber`	long	The run number of the loading task. The value increases when the task is restarted.
`retryNumber`	long	The retry number of the loading task. The value increases when the task is automatically retried during a run.
`status`	string	The current status of the loading task. LOAD_COMPLETED: The task is loaded successfully.
`totalTimeSpent`	long	The time spent on the loading task, in milliseconds (ms). This includes the time to fetch the file list, parse and download the files, and load the files into the database instance.
`totalRecords`	long	The total number of records that have been loaded.
`totalDuplicates`	long	The number of duplicate records.
`parsingErrors`	long	The number of parsing errors.
`datatypeMismatchErrors`	long	The number of records whose data type does not match the specified data type.
`insertErrors`	long	The number of records that failed to be inserted due to errors.
`loaderId`	string	The ID of the loading task.
`errors`	List	A list of error logs. A maximum of 1,000 records are retained. The logs are purged after being read.

If the query is successful, "200 OK" is returned. For information about other error responses, see List of error messages.

Cancel an import task

You can send an HTTP DELETE request to the <gdb-endpoint>:<port>/loader endpoint to cancel an import task.

Note

To cancel an import task, you must include <loaderId> as a URL parameter. You can also append <loaderId> to the URL path.

Request syntax
```
DELETE <gdb-endpoint>:<port>/loader?loaderId=<loaderId>

DELETE <gdb-endpoint>:<port>/loader/<loaderId>
```
Note
- <gdb-endpoint>: The endpoint (internal or public) of the GDB instance.
- <port>: The port (internal or public) that corresponds to the endpoint of the GDB instance.
- <loaderId>: The ID of the import task that you want to cancel.
After the cancellation request is complete, the server purges the record of the task. If the task cancellation fails, identify the cause, resolve the issue, and then try to cancel the task again.
Response syntax
```
no response body
```
The HTTP status code indicates the result of the request. A successful request returns "200 OK". For information about other error responses, see List of error messages.