Return to top
On this page

HTTP API

Introduction

The GreptimeDB HTTP API is based on standard HTTP protocol and is easy to work with off-the-shelf HTTP clients.

The GreptimeDB dashboard is a web console based on HTTP API.

Available API:

  • /sql
  • /promql
  • /scripts and /run-script
  • /opentsdb to support OpenTSDB protocol
  • /influxdb to support InfluxDB line protocol
  • /prometheus to support Prometheus Endpoints

All these APIs are under the parent resource /v1, which specifies the current HTTP API version.

/sql

/sql executes SQL statements and returns results.

For more information about SQL, please refer to the SQL reference document.

For example:

shell
curl -G  http://localhost:4000/v1/sql  --data-urlencode "sql=select * from numbers limit 5"

/sql also supports POST method:

shell
curl http://localhost:4000/v1/sql -d "sql=select * from numbers limit 5"

The returned JSON result is shown below:

json
{
  "code": 0,
  "output": [{
    "records": {
      "schema": {
        "column_schemas": [
          {
            "name": "number",
            "data_type": "UInt32"
          }
        ]
      },
      "rows": [
        [
          0
        ],
        [
          1
        ],
        [
          2
        ],
        [
          3
        ],
        [
          4
        ]
      ]
    }
  }],
  "execution_time_ms": 2
}

Parameters and Result

/sql only accepts one parameter:

  • sql: the SQL statement.

The API Result contains:

  • code: the result integer code. Zero means success, otherwise failure.
  • output: the SQL executed result, including schema and rows.

Examples

Create table via SQL:

shell
curl  -v -XPOST -G  http://localhost:4000/v1/sql  --data-urlencode "sql=CREATE TABLE HTTP_API_TEST(name STRING, value DOUBLE, ts TIMESTAMP default CURRENT_TIMESTAMP, PRIMARY KEY(name), TIME INDEX(ts))"
json
{"code":0,"output":[{"affectedrows":1}],"execution_time_ms":10}

Insert data:

shell
 curl  -v -XPOST -G http://localhost:4000/v1/sql  --data-urlencode "sql=INSERT INTO HTTP_API_TEST(name, value) VALUES('hello', 1), ('world', 2)"
json
{"code":0,"output":[{"affectedrows":2}],"execution_time_ms":6}

Query data:

shell
 curl -v -XGET -G http://localhost:4000/v1/sql  --data-urlencode "sql=SELECT * from HTTP_API_TEST"
json
{
  "code": 0,
  "output": [{
    "records": {
      "schema": {
        "column_schemas": [
          {
            "name": "name",
            "data_type": "String"
          },
          {
            "name": "value",
            "data_type": "Float64"
          },
          {
            "name": "ts",
            "data_type": "Timestamp"
          }
        ]
      },
      "rows": [
        [
          "hello",
          1,
          1667802991224
        ],
        [
          "world",
          2,
          1667802991224
        ]
      ]
    }
  }],
  "execution_time_ms": 7
}

/promql

/promql executes PromQL statements and returns corresponding results. For more information about PromQL, please refer to the PromQL reference document.

You can find details of the interface in the Use-PromQL document.

/scripts and /run-script

/scripts submits a Python script into GreptimeDB.

Save a python script such as test.py:

python
@coprocessor(args = ["number"],
             returns = [ "number" ],
             sql = "select number from numbers limit 5")
def square(number):
    return number * 2

Submits it to database:

shell
curl --data-binary @test.py -XPOST \
      "http://localhost:4000/v1/scripts?db=default&name=square"
json
{"code":0}

The python script is inserted into the scripts table and compiled automatically:

shell
curl -G  http://localhost:4000/v1/sql  --data-urlencode "sql=select * from scripts"
json
{
  "code": 0,
  "output": [{
    "records": {
      "schema": {
        "column_schemas": [
          {
            "name": "schema",
            "data_type": "String"
          },
          {
            "name": "name",
            "data_type": "String"
          },
          {
            "name": "script",
            "data_type": "String"
          },
          {
            "name": "engine",
            "data_type": "String"
          },
          {
            "name": "timestamp",
            "data_type": "TimestampMillisecond"
          },
          {
            "name": "gmt_created",
            "data_type": "TimestampMillisecond"
          },
          {
            "name": "gmt_modified",
            "data_type": "TimestampMillisecond"
          }
        ]
      },
      "rows": [
        [
          "default",
          "square",
          "@coprocessor(args = [\"number\"],\n             returns = [ \"number\" ],\n             sql = \"select number from numbers\")\ndef square(number):\n    return number * 2\n",
          "python",
          0,
          1676032587204,
          1676032587204
        ]
      ]
    }
  }],
  "execution_time_ms": 4
}

You can also execute the script via /run-script:

shell
curl -XPOST -G "http://localhost:4000/v1/run-script?db=default&name=square"
json
{
  "code": 0,
  "output": [{
    "records": {
      "schema": {
        "column_schemas": [
          {
            "name": "number",
            "data_type": "Float64"
          }
        ]
      },
      "rows": [
        [
          0
        ],
        [
          2
        ],
        [
          4
        ],
        [
          6
        ],
        [
          8
        ]
      ]
    }
  }],
  "execution_time_ms": 8
}

Parameters and Result for Python scripts

/scripts accepts query parameters db which specifies the database, and name which names the script. /scripts processes the POST method body as the script file content.

/run-script runs the compiled script by db and name, then returns the output which is the same as the query result in /sql API.

/run-script also receives other query parameters as the user params passed into the coprocessor, refer to Input and Output.

OpenAPI docs

An OAS compatible OpenAPI specification is available at http://localhost:4000/v1/private/api.json. We also provided Redoc UI at http://localhost:4000/v1/private/docs for convenience.

Result codes table

CodeDescription
0success
1000Unknown error
1001Unsupported operation
1002Unexpected error, maybe there is a BUG
1003Internal error
1004Invalid arguments
2000SQL syntax error
3000Fail to create a plan for the query
3001Fail to execute a query plan
4000Table already exists
4001Table not found
4002Column not found
4003Column already exists
4004Database not found
5000Storage is temporarily unable to handle the request
6000Runtime resources exhausted
7000User not found
7001Unsupported password type
7002Username and password does not match
7003Http authorization header not found
7004Invalid http authorization header
7005Illegal request to connect catalog-schema