Pivot connections API

You can use the Pivot connections API to create, read, and modify connections to Apache Druid.

Before you start to set up connections, make sure your Pivot server configuration doesn't include a definition for fixedConnections.

Pivot must be running in native users mode.

Get all connections

Returns a list of all connections.

URL

GET /api/v1/connections

Success response

Code	Description
200	"status": "ok"

Sample request

curl -X GET 'http://PIVOT_URL/api/v1/connections' \
--header 'x-imply-api-token:<token>'

Sample response

{
  "connections": [
    {
      "name": "druid1",
      "type": "druid",
      "queryHosts": [
        "localhost"
      ],
      "title": "Druid 1",
      "timeout": 40000
    },
    {
      "name": "druid2",
      "type": "druidsql",
      "queryHosts": [
        "https://www.example.com:8888"
      ],
      "title": "Druid 2",
      "timeout": 50000
    }
  ]
}

Get a connection

Returns a connection with a specified name.

URL

GET /api/v1/connections/{name}

Success response

Code	Description
200	"status": "ok"

Sample error response

Code	Example body
404 Not Found	"error": "This connection does not exist."

Sample request

curl -X GET 'http://PIVOT_URL/api/v1/connections/druid1' \
--header 'x-imply-api-token:<token>'

Sample response

{
      "name": "druid1",
      "type": "druid",
      "queryHosts": [
        "localhost"
      ],
      "title": "Druid 1",
      "timeout": 40000
    }

Create a connection

Creates a connection with a specified name.

URL

POST /api/v1/connections

Connection properties

The required connection properties depend upon the protocol used for the connection. Connection properties are as follows:

• name: Connection name/ID.

• type: Connection type—druid or druidsql.

• queryHosts: Array of hostnames and ports to connect to.

• title: Descriptive title for the connection. Appears as the connection Name in the Pivot UI.

• timeout: Connection timeout in milliseconds.

• defaultDbAuthToken: An object that defines the default token to use for authentication—for example:
  

  "defaultDbAuthToken": {
  "type": "basic-auth",
    "username": "admin",
    "password": "admin_password"
  }

• protocol: Protocol type. One of:
  - plain: Plain text (default).
  - tls: Transport Layer Security.
  - tls-loose: A TLS connection that doesn't check the certificate (use for testing only).

• ca: Applies when protocol is tls. Trusted certificate, if using self-signed certificates.

• cert: Applies when protocol is tls. Client-side certificate.

• key: Applies when protocol is tls. Private key filename.

• passphrase: Applies when protocol is tls. Passphrase for the private key, if required.

• decorator: An optional JavaScript file to decorate Druid requests prior to sending them.

• decoratorOptions: An object that defines decorator options.

• sockHost: Proxy hostname for connections made via a SOCKS proxy.

• sockUsername: User for the SOCKS proxy.

• sockPassword: Password for the SOCKS proxy.

Sample request

curl -X POST 'http://PIVOT_URL/api/v1/connections' \
--header 'x-imply-api-token: <token>' \
--header 'Content-Type: application/json' \
--data-raw '{
      "name": "druid1",
      "type": "druid",
      "queryHosts": [
        "localhost"
      ],
      "title": "Druid 1",
      "timeout": 40000
    }'

Success response

Code	Description
200	"status": "ok"

Sample error response

Code	Example body
400 Bad Request	"error": "this name has been used."

Sample response

{
    "status": "ok",
    "message": "Created successfully",
    "connection": {
      "name": "druid1",
      "type": "druid",
      "queryHosts": [
        "localhost"
      ],
      "title": "Druid 1",
      "timeout": 40000
    }
}

Update a connection

Updates the details of a connection with a specified name. See Connection properties for a description of all properties.

URL

POST /api/v1/connections/{name}

Sample request

The following example request updates the queryHosts, title, and timeout properties of the druid1 connection object. The name in the request body must match the {name} in the URL. You can't update the name field.

You must provide all connection properties you want to retain in the connection, even if you don't want to update them. Pivot recreates the connection with the details you specify in the request.

curl -X POST 'http://PIVOT_URL/api/v1/connections/Analyst' \
--header 'x-imply-api-token: <token>' \
--header 'Content-Type: application/json' \
--data-raw '{
      "name": "druid1",
      "type": "druid",
      "queryHosts": [
        "example.amazonaws.com:9088"
      ],
      "title": "Druid AWS",
      "timeout": 30000
    }'

Success response

Code	Description
200	"status": "ok"

Sample error response

Code	Example body
400 Not Found	"error": "this connection does not exist"

Sample response

{
    "status": "ok",
    "message": "Updated successfully",
    "connection": {
      "name": "druid1",
      "type": "druid",
      "queryHosts": [
        "example.amazonaws.com:9088"
      ],
      "title": "Druid AWS",
      "timeout": 30000
    }
}

Delete a connection

Deletes a connection with a specified name.

URL

DELETE /api/v1/connections/{name}

Sample request

curl -X DELETE 'http://PIVOT_URL/api/v1/connections/druid1' \
--header 'x-imply-api-token:<token>'

Success response

Code	Description
200	"status": "ok"

Sample error response

Code	Example body
404 Not Found	"error": "This connection does not exist. Please check the name again."

Sample response

{
    "status": "ok",
    "message": "Deleted successfully"
}