======== SCQL API ======== SCQL supports two types of APIs: synchronous and asynchronous. The synchronous interface is suitable for executing fast queries, such as DDL, DML, and simple DQL. Meanwhile, the asynchronous interface is recommended when the query may take a long time to run. Asynchronous ============ public/submit_query ------------------- Submit the query (DDL/DML/DQL) to SCQL, SCQL will return a session ID immediately which can be used to fetch result, and processes the query in the background. Request ^^^^^^^ +---------------------------+-----------------+----------+-------------------------------------------------------------------------------+ | Field | Type | Required | Description | +===========================+=================+==========+===============================================================================+ | header | RequestHeader_ | N | Common request header | +---------------------------+-----------------+----------+-------------------------------------------------------------------------------+ | user | SCDBCredential_ | Y | User information | +---------------------------+-----------------+----------+-------------------------------------------------------------------------------+ | query | string | Y | SCQL query to be run | +---------------------------+-----------------+----------+-------------------------------------------------------------------------------+ | .. _callback_url: | | | | | | string | N | callback URL to report query result. See `Asynchronous send result`_ for more | | query_result_callback_url | | | | +---------------------------+-----------------+----------+-------------------------------------------------------------------------------+ | biz_request_id | string | N | Biz request id which often be unique per biz action | +---------------------------+-----------------+----------+-------------------------------------------------------------------------------+ | db_name | string | N | Current database name | +---------------------------+-----------------+----------+-------------------------------------------------------------------------------+ Response ^^^^^^^^ +-----------------+---------+-----------------------------------------+ | Field | Type | Description | +=================+=========+=========================================+ | status | Status_ | See `Status code`_ for more information | +-----------------+---------+-----------------------------------------+ | .. _session_id: | | | | | string | Unique ID of a session | | scdb_session_id | | | +-----------------+---------+-----------------------------------------+ Example ^^^^^^^^ If you want execute `show databases`, the request and response message should be structured as follows: * request .. code-block:: javascript { "user": { "user": { "account_system_type": "NATIVE_USER", "native_user": { "name": "someuser", "password": "somepassword" } }, "grm_token": "sometoken" }, "query": "show databases;", "biz_request_id": "1234" } * response .. code-block:: javascript { "status": { "code": 0, "message": "", "details": [] }, "scdb_session_id": "some_session_id" } public/fetch_result --------------------- Fetch result of the query submitted via the "submit_query" method before, if the query is still running, It will return `NOT_READY` status code. Request ^^^^^^^ +-----------------+-----------------+----------+-------------------------------------------------------------------+ | Field | Type | Required | Description | +=================+=================+==========+===================================================================+ | header | RequestHeader_ | N | Common request header | +-----------------+-----------------+----------+-------------------------------------------------------------------+ | user | SCDBCredential_ | Y | User information | +-----------------+-----------------+----------+-------------------------------------------------------------------+ | scdb_session_id | string | Y | Given by scdb when submit the query before, same with session_id_ | +-----------------+-----------------+----------+-------------------------------------------------------------------+ Response ^^^^^^^^ +-------------------+--------------------+-----------------------------------------+ | Field | Type | Description | +===================+====================+=========================================+ | status | Status_ | See `Status code`_ for more information | +-------------------+--------------------+-----------------------------------------+ | out_columns | Tensor_ list | Query result | +-------------------+--------------------+-----------------------------------------+ | scdb_session_id | string | Same with session_id_ | +-------------------+--------------------+-----------------------------------------+ | affected_rows | int64 | The num of rows affected | +-------------------+--------------------+-----------------------------------------+ Example ^^^^^^^^ If you want to get the result of the query `show databases`, you can send a request like this. .. code-block:: javascript { "user": { "user": { "account_system_type": "NATIVE_USER", "native_user": { "name": "some_user", "password": "some_password" } }, "grm_token": "some_token" }, "scdb_session_id": "some_session_id" } If succeed, a response will be received with status code 0 like this: .. code-block:: javascript { "status": { "code": 0, "message": "", "details": [] }, "out_columns": [ { "name": "Database", "shape": { "dim": [ { "dim_value": "1" }, { "dim_value": "1" } ] }, "elem_type": "STRING", "option": "VALUE", "annotation": null, "ss": { "ss": [ "scdb" ] } } ], "scdb_session_id": "some_session_id", "affected_rows": "0", "execution_process": null } If result is not ready, the response can be show as follows: .. code-block:: javascript { "status": { "code": 104, "message": "result not ready, please retry later", "details": [] }, "out_columns": [], "scdb_session_id": "some_session_id", "affected_rows": "0", "execution_process": null } Asynchronous send result ------------------------ Automatically send the result to the user by post the following message when the result is available. To accomplish this, :ref:`query_result_callback_url ` should be set. +-------------------+--------------------+----------+-------------------------------------------------------------------+ | Field | Type | Required | Description | +===================+====================+==========+===================================================================+ | status | Status_ | Y | See `Status code`_ for more information | +-------------------+--------------------+----------+-------------------------------------------------------------------+ | out_columns | Tensor_ list | Y | Query result, See Tensor_ for more information | +-------------------+--------------------+----------+-------------------------------------------------------------------+ | scdb_session_id | string | Y | Given by scdb when submit the query before, same with session_id_ | +-------------------+--------------------+----------+-------------------------------------------------------------------+ | affected_rows | int64 | Y | The num of rows affected | +-------------------+--------------------+----------+-------------------------------------------------------------------+ Synchronous =========== public/submit_and_get --------------------- Submit a query to SCQL, SCQL will wait for all tasks to complete before returning the result to the use. Request ^^^^^^^ +----------------+-----------------+----------+-----------------------------------------------------+ | Field | Type | Required | Description | +================+=================+==========+=====================================================+ | header | RequestHeader_ | N | Common request header | +----------------+-----------------+----------+-----------------------------------------------------+ | user | SCDBCredential_ | Y | User information | +----------------+-----------------+----------+-----------------------------------------------------+ | query | string | Y | SCQL query to be run | +----------------+-----------------+----------+-----------------------------------------------------+ | biz_request_id | string | N | Biz request id which often be unique per biz action | +----------------+-----------------+----------+-----------------------------------------------------+ | db_name | string | Y | Current database name | +----------------+-----------------+----------+-----------------------------------------------------+ Response ^^^^^^^^ +-------------------+--------------------+-------------------------------------------------+ | Field | Type | Description | +===================+====================+=================================================+ | status | Status_ | See `Status code`_ for more information | +-------------------+--------------------+-------------------------------------------------+ | out_columns | Tensor_ list | Query result, See `Tensor` for more information | +-------------------+--------------------+-------------------------------------------------+ | scdb_session_id | string | SCDB session id | +-------------------+--------------------+-------------------------------------------------+ | affected_rows | int64 | The num of rows affected | +-------------------+--------------------+-------------------------------------------------+ Example ^^^^^^^^ If you want submit a query `show databases`, you can send a request as follows: .. code-block:: javascript { "user": { "user": { "account_system_type": "NATIVE_USER", "native_user": { "name": "someuser", "password": "somepassword" } }, "grm_token": "sometoken" }, "query": "show databases;", "biz_request_id": "1234", "db_name": "scdb" } If successful, a response will be received like this: .. code-block:: javascript { "status": { "code": 0, "message": "", "details": [] }, "out_columns": [ { "name": "Database", "shape": { "dim": [ { "dim_value": "1" }, { "dim_value": "1" } ] }, "elem_type": "STRING", "option": "VALUE", "annotation": null, "ss": { "ss": [ "scdb" ] } } ], "scdb_session_id": "some_session_id", "affected_rows": "0", "execution_process": null } Message Structure ================= RequestHeader ------------- +----------------+---------------------+----------+--------------------------------------------------+ | Field | Type | Required | Description | +================+=====================+==========+==================================================+ | custom_headers | map | Y | Custom headers used to record custom information | +----------------+---------------------+----------+--------------------------------------------------+ .. _scdb_credential: SCDBCredential -------------- +-----------+--------+----------+----------------------------------------------+ | Field | Type | Required | Description | +===========+========+==========+==============================================+ | user | User_ | Y | User information, contains password and name | +-----------+--------+----------+----------------------------------------------+ | grm_token | string | Y | The unique identifier of the user in GRM | +-----------+--------+----------+----------------------------------------------+ User ^^^^ +---------------------+--------------------+----------+-------------------------+ | Field | Type | Required | Description | +=====================+====================+==========+=========================+ | account_system_type | AccountSystemType_ | Y | Account Type | +---------------------+--------------------+----------+-------------------------+ | native_user | NativeUser_ | Y | Native user information | +---------------------+--------------------+----------+-------------------------+ NativeUser """""""""" +----------+--------+----------+-------------+ | Field | Type | Required | Description | +==========+========+==========+=============+ | name | string | Y | username | +----------+--------+----------+-------------+ | password | string | Y | password | +----------+--------+----------+-------------+ Tensor ------ +------------+--------------------+----------+--------------------------------------------------------------------------------------+ | Field | Type | Required | Description | +============+====================+==========+======================================================================================+ | name | string | Y | Tensor name | +------------+--------------------+----------+--------------------------------------------------------------------------------------+ | shape | TensorShape_ | Y | It's normally [M] (a vector with M elements) | +------------+--------------------+----------+--------------------------------------------------------------------------------------+ | elem_type | PrimitiveDataType_ | Y | Type of date | +------------+--------------------+----------+--------------------------------------------------------------------------------------+ | option | TensorOptions_ | Y | Tensor options | +------------+--------------------+----------+--------------------------------------------------------------------------------------+ | annotation | TensorAnnotation_ | N | Carries physical status information, It MUST be there if the