Databases

• 1: GET databases
• 2: POST databases
• 3: GET databases/:database_name
• 4: PUT databases/:database_name
• 5: DELETE databases/:database_name
• 6: GET databases/:database_name/configuration
• 7: PUT databases/:database_name/configuration
• 8: GET databases/:database_name/hosts
• 9: POST databases/:database_name/hosts
• 10: DELETE databases/:database_name/hosts/:host_id
• 11: POST databases/:database_name/hosts/:host_id/process
• 12: GET databases/:database_name/license
• 13: GET databases/:database_name/licenses
• 14: DELETE databases/:database_name/hosts/:host_id/process
• 15: POST databases/:database_name/hosts/:host_id/replace_with/:host_id_new
• 16: GET databases/:database_name/nodes
• 17: GET databases/:database_name/nodes/:node_id
• 18: POST databases/:database_name/process
• 19: GET databases/:database_name/process
• 20: DELETE databases/:database_name/process
• 21: POST databases/:database_name/rebalance/process
• 22: POST databases/:database_name/Workload analyzer/process

1 - GET databases

Returns a list of databases, their current status, and database properties.

Resource URL

https://<NODE>:5444/databases

The API key must have restricted level security or higher.

Parameters

None.

Example request

An example of the full request using cURL:

curl -H "VerticaApiKey: ValidAPIKey" https://<NODE>:5444/databases

Response:

{
    "body": [
        {
            "href": "/databases/VMart",
            "mime-type": [
                "application/vertica.database.json-v2"
            ],
            "name": "VMart",
            "port": "5433",
            "status": "UP"
        },
        {
            "href": "/databases/testDB",
            "mime-type": [
                "application/vertica.database.json-v2"
            ],
            "name": "testDB",
            "port": "5433",
            "status": "DOWN"
        }
    ],
    "href": "/databases",
    "links": [
        "/:database_name"
    ],
    "mime-type": "application/vertica.databases.json-v2"
}

2 - POST databases

Creates a job to create a new database with the provided parameters.

Returns a job ID that can be used to determine the status of the job. See GET jobs.

Resource URL

https://<NODE>:5444/databases

The API key must have admin level security.

Parameters

Example request

https://:5444/databases?passwd=db_password&name=db_name&
catalog=%2Fpath%2Fto%2Fcatalog&data=%2Fpath%2Fto%2Fdata_directory

Response:

{
    "jobid": "CreateDatabase-testDB-2014-07-07 15:49:53.219445",
    "resource": "/jobs/CreateDatabase-testDB-2014-07-07 15:49:53.219445",
    "userid": "dbadmin"
}

3 - GET databases/:database_name

Returns details about a specific database. The :database_name is the value of the name field that the GET databases command returns.

Resource URL

https://<NODE>:5444/databases/:database_name

The API key must have restricted level security or higher.

Parameters

None.

Example request

Response:

{
    "body": {
        "database_id": "VMart",
        "id": "VMart",
        "nodes": "v_vmart_node0001,v_vmart_node0002,v_vmart_node0003",
        "nodes_new": [
            {
                "catalog_base": "/home/dbadmin",
                "data_base": "/home/dbadmin",
                "host": "10.20.100.247",
                "id": "v_vmart_node0001"
            },
            {
                "catalog_base": "/home/dbadmin",
                "data_base": "/home/dbadmin",
                "host": "10.20.100.248",
                "id": "v_vmart_node0002"
            },
            {
                "catalog_base": "/home/dbadmin",
                "data_base": "/home/dbadmin",
                "host": "10.20.100.249",
                "id": "v_vmart_node0003"
            }
        ],
        "path": "/home/dbadmin/VMart",
        "port": "5433",
        "restartpolicy": "ksafe",
        "status": "UP"
    },
    "href": "/databases/VMart",
    "links": [
        "/configuration",
        "/hosts",
        "/license",
        "/nodes",
        "/process",
        "/rebalance/process",
        "/status",
        "/Workload Analyzer/process"
    ],
    "mime-type": "application/vertica.database.json-v2"
}

4 - PUT databases/:database_name

Creates a job to run the action specified by the action parameter against the database identified by :database_name. The :database_name is the value of the name field that the GET databases command returns.

Returns a job ID that you can use to determine the status of the job. See GET jobs.

Resource URL

https://<NODE>:5444/databases/:database_name

The API key must have normal level security or higher.

Parameters

Example request

Response:

{
    "id": "StopDatabase-testDB-2014-07-20 13:28:49.321744",
    "url": "/jobs/StopDatabase-testDB-2014-07-20 13:28:49.321744"
}

5 - DELETE databases/:database_name

Creates a job to delete (drop) an existing database on the cluster. To perform this operation, you must first stop the database. The :database_name is the value of the name field that the GET databases command returns.

Returns a job ID that you can use to determine the status of the job. See GET jobs.

Resource URL

https://<NODE>:5444/databases/:database_name

The API key must have admin level security.

Parameters

None.

Example request

Response:

{
    "id": "DropDatabase-TestDB-2014-07-18 12:50:33.332383",
    "url": "/jobs/DropDatabase-TestDB-2014-07-18 12:50:33.332383"
}

6 - GET databases/:database_name/configuration

Returns a list of configuration parameters for the database identified by :database_name. The :database_name is the value of the name field that the GET databases command returns.

Resource URL

https://<NODE>:5444/databases/:database_name/configuration

The API key must have restricted level security or higher.

Parameters

Example request

Response:

This API call returns over 100 configuration parameters.. The following response is a small subset of the total amount returned.

[
    {
        "node_name": "ALL",
        "parameter_name": "ACDAlgorithmForSynopsisVersion1",
        "current_value": "1",
        "restart_value": "1",
        "database_value": "1",
        "default_value": "1",
        "current_level": "DEFAULT",
        "restart_level": "DEFAULT",
        "is_mismatch": "f",
        "groups": "",
        "allowed_levels": "SESSION, DATABASE",
        "superuser_visible_only": "f",
        "change_under_support_guidance": "t",
        "change_requires_restart": "f",
        "description": "Algorithm used to interpret synopsis version 1 for approximate count distinct"
    },
    {
        "node_name": "ALL",
        "parameter_name": "ACDLinearCountThreshold",
        "current_value": "-1.000000",
        "restart_value": "-1.000000",
        "database_value": "-1.000000",
        "default_value": "-1.000000",
        "current_level": "DEFAULT",
        "restart_level": "DEFAULT",
        "is_mismatch": "f",
        "groups": "",
        "allowed_levels": "SESSION, DATABASE",
        "superuser_visible_only": "f",
        "change_under_support_guidance": "t",
        "change_requires_restart": "f",
        "description": "If positive, will overwrite the default linear counting threshold in approximate count distinct"
    },
    {
        "node_name": "ALL",
        "parameter_name": "ACDSynopsisVersion",
        "current_value": "2",
        "restart_value": "2",
        "database_value": "2",
        "default_value": "2",
        "current_level": "DEFAULT",
        "restart_level": "DEFAULT",
        "is_mismatch": "f",
        "groups": "",
        "allowed_levels": "SESSION, DATABASE",
        "superuser_visible_only": "f",
        "change_under_support_guidance": "t",
        "change_requires_restart": "f",
        "description": "Default synopsis version to be generated by approximate count distinct"
    },
    {
        "node_name": "ALL",
        "parameter_name": "AHMBackupManagement",
        "current_value": "0",
        "restart_value": "0",
        "database_value": "0",
        "default_value": "0",
        "current_level": "DEFAULT",
        "restart_level": "DEFAULT",
        "is_mismatch": "f",
        "groups": "",
        "allowed_levels": "NODE, DATABASE",
        "superuser_visible_only": "f",
        "change_under_support_guidance": "t",
        "change_requires_restart": "f",
        "description": "Consider backup epochs when setting new AHM"
    },
    {
        "node_name": "ALL",
        "parameter_name": "ARCCommitPercentage",
        "current_value": "3.000000",
        "restart_value": "3.000000",
        "database_value": "3.000000",
        "default_value": "3.000000",
        "current_level": "DEFAULT",
        "restart_level": "DEFAULT",
        "is_mismatch": "f",
        "groups": "",
        "allowed_levels": "DATABASE",
        "superuser_visible_only": "f",
        "change_under_support_guidance": "t",
        "change_requires_restart": "f",
        "description": "ARC will commit only if the change is more than the percentage specified"
    },
    {
        "node_name": "ALL",
        "parameter_name": "AWSCAFile",
        "current_value": "",
        "restart_value": "",
        "database_value": "",
        "default_value": "",
        "current_level": "DEFAULT",
        "restart_level": "DEFAULT",
        "is_mismatch": "f",
        "groups": "",
        "allowed_levels": "DATABASE",
        "superuser_visible_only": "f",
        "change_under_support_guidance": "f",
        "change_requires_restart": "f",
        "description": "Overrides the default CA file"
    },
    ...
]

7 - PUT databases/:database_name/configuration

Sets one or more configuration parameters for the database identified by :database_name. The :database_name is the value of the name field that the GET databases command returns.

Returns the parameter name, the requested value, and the result of the attempted change (Success or Failed).

Resource URL

https://<NODE>:5444/databases/:database_name/configuration

The API key must have admin level security.

Parameters

Example request

https://:5444/databases/testDB/configuration?user_id=username&passwd=username_password
&JavaBinaryForUDx=%2Fusr%2Fbin%2Fjava&TransactionIsolationLevel=SERIALIZABLE

Response:

[
    {
        "key": "JavaBinaryForUDx",
        "result": "Success",
        "value": "/usr/bin/java"
    },
    {
        "key": "TransactionIsolationLevel",
        "result": "Success",
        "value": "SERIALIZABLE"
    }
]

8 - GET databases/:database_name/hosts

Returns the hostname/IP address, node name, and UP/DOWN status of each host associated with the database identified by :database_name. The :database_name is the value of the name field that the GET databases command returns.

Resource URL

https://<NODE>:5444/databases/:database_name/hosts

The API key must have restricted level security or higher.

Parameters

None.

Example request

Response:

{
    "body": [
        {
            "hostname": "10.20.100.247",
            "nodename": "v_vmart_node0001",
            "status": "UP",
            "ts": "2014-07-18T13:12:31.904191"
        },
        {
            "hostname": "10.20.100.248",
            "nodename": "v_vmart_node0002",
            "status": "UP",
            "ts": "2014-07-18T13:12:31.904209"
        },
        {
            "hostname": "10.20.100.249",
            "nodename": "v_vmart_node0003",
            "status": "UP",
            "ts": "2014-07-18T13:12:31.904215"
        }
    ],
    "href": "/databases/VMart/hosts",
    "links": [],
    "mime-type": "application/vertica.hosts.json-v2"
}

9 - POST databases/:database_name/hosts

Creates a job to add a host to the database identified by :database_name. This host must already be part of the cluster. The :database_name is the value of the name field that the GET databases command returns.

Returns a job ID that you can use to determine the status of the job. See GET jobs.

Resource URL

https://<NODE>:5444/databases/:database_name/hosts

The API key must have admin level security.

Parameters

Example request

Response:

{
    "id": "AddHostToDatabase-testDB-2014-07-20 12:24:04.088812",
    "url": "/jobs/AddHostToDatabase-testDB-2014-07-20 12:24:04.088812"
}

10 - DELETE databases/:database_name/hosts/:host_id

Creates a job to remove the host identified by :host_id from the database identified by :database_name. The :database_name is the value of the name field that the GET databases command returns. The :host_id is the value of the host field returned by GET databases/:database_name.

Returns a job ID that you can use to determine the status of the job. See GET jobs.

Resource URL

https://<NODE>:5444/databases/:database_name/hosts/:host_id

The API key must have admin level security.

Parameters

Example request

Response:

{
    "id": "RemoveHostFromDatabase-testDB-2014-07-20 13:41:15.646235",
    "url": "/jobs/RemoveHostFromDatabase-testDB-2014-07-20 13:41:15.646235"
}

11 - POST databases/:database_name/hosts/:host_id/process

Creates a job to start the vertica process for the database identified by :database_name on the host identified by :host_id. The :database_name is the value of the name field that the GET databases command returns. The :host_id is the value of the host field returned by GET databases/:database_name.

Returns a job ID that you can use to determine the status of the job. See GET jobs.

Resource URL

https://<NODE>:5444/databases/:database_name/hosts/:host_id/process

The API key must have restricted level security or higher.

Parameters

None.

Example request

Response:

{
    "id": "StartDatabase-testDB-2014-07-20 13:14:03.968340",
    "url": "/jobs/StartDatabase-testDB-2014-07-20 13:14:03.968340"
}

12 - GET databases/:database_name/license

Returns details about the database license being used by the database identified by :database_name. The :database_name is the value of the name field that the GET databases command returns.

Resource URL

https://<NODE>:5444/:database_name/license

The API key must have restricted level security or higher.

Parameters

Example request

Response:

{
    "body": {
        "details": {
            "assigned_to": "Vertica Systems, Inc.",
            "grace_period": 0,
            "is_ce": false,
            "is_unlimited": false,
            "name": "vertica",
            "not_after": "Perpetual",
            "not_before": "2007-08-03"
        },
        "last_audit": {
            "audit_date": "2014-07-18 13:49:22.530105-04",
            "database_size_bytes": "814060522",
            "license_size_bytes": "536870912000",
            "usage_percent": "0.00151630588248372"
        }
    },
    "href": "/databases/VMart/license",
    "links": [],
    "mime-type": "application/vertica.license.json-v2"
}

13 - GET databases/:database_name/licenses

Returns details about all license being used by the database identified by :database_name. The :database_name is the value of the name field that the GET databases command returns.

Resource URL

https://<NODE>:5444/:database_name/licenses

The API key must have restricted level security or higher.

Parameters

Example request

Response:

{
    "body": [
        {
            "details": {
                "assigned_to": "Vertica Systems, Inc.",
                "audit_date": "2014-07-19 21:35:25.111312",
                "is_ce": "False",
                "name": "vertica",
                "node_restriction": "",
                "not_after": "Perpetual",
                "not_before": "2007-08-03",
                "size": "500GB"
            },
            "last_audit": {
                "audit_date": "2014-07-19 21:35:26.318378-04",
                "database_size_bytes": "819066288",
                "license_size_bytes": "536870912000",
                "usage_percent": "0.00152562984824181"
            }
        },
        {
            "details": {
                "assigned_to": "Vertica Systems, Inc., FlexTable",
                "audit_date": "2014-07-19 21:35:25.111312",
                "is_ce": "False",
                "name": "com.vertica.flextable",
                "node_restriction": "",
                "not_after": "Perpetual",
                "not_before": "2007-08-03",
                "size": "500GB"
            },
            "last_audit": {
                "audit_date": "2014-07-19 21:35:25.111312",
                "database_size_bytes": 0,
                "license_size_bytes": 536870912000,
                "usage_percent": 0
            }
        }
    ],
    "href": "/databases/VMart/licenses",
    "links": [],
    "mime-type": "application/vertica.features.json-v2"
}

14 - DELETE databases/:database_name/hosts/:host_id/process

Creates a job to stop the vertica process for the database identified by :database_name on the host identified by :host_id. The :database_name is the value of the name field that the GET databases command returns. The :host_id is the value of the host field returned by GET databases/:database_name.

Returns a job ID that can be used to determine the status of the job. See GET jobs.

Resource URL

https://<NODE>:5444/databases/:database_name/hosts/:host_id/process

The API key must have restricted level security or higher.

Parameters

None.

Example request

Response:

{
    "id": "StopDatabase-testDB-2014-07-20 13:02:08.453547",
    "url": "/jobs/StopDatabase-testDB-2014-07-20 13:02:08.453547"
}

15 - POST databases/:database_name/hosts/:host_id/replace_with/:host_id_new

Creates a job to replace the host identified by hosts/:host_id with the host identified by replace_with/:host_id. Vertica performs these operations for the database identified by :database_name. The :database_name is the value of the name field that the GET databases command returns. The :host_id is the value of the host field as returned by GET databases/:database_name. You can find valid replacement hosts using GET hosts. The replacement host cannot already be part of the database. You must stop the vertica process on the host being replaced.

Returns a job ID that you can use to determine the status of the job. See GET jobs.

Resource URL

https://<NODE>:5444/databases/:database_name/hosts/:host_id/replace_with/:host_id_new

The API key must have admin level security.

Parameters

Example request

Response:

{
    "id": "ReplaceNode-testDB-2014-07-20 13:50:28.423509",
    "url": "/jobs/ReplaceNode-testDB-2014-07-20 13:50:28.423509"
}

16 - GET databases/:database_name/nodes

Returns a comma-separated list of node IDs for the database identified by :database_name. The :database_name is the value of the name field that the GET databases command returns.

Resource URL

https://<NODE>:5444/:database_name/nodes

The API key must have restricted level security or higher.

Parameters

None.

Example request

Response:

[
    {
        "database_id": "VMart",
        "node_id": "v_vmart_node0001,v_vmart_node0002,v_vmart_node0003",
        "status": "Unknown"
    }
]

17 - GET databases/:database_name/nodes/:node_id

Returns details about the node identified by :node_id. The :node_id is one of the node IDs returned by GET databases/:database_name/nodes.

Resource URL

https://<NODE>:5444/:database_name/nodes/:node_id

The API key must have restricted level security or higher.

Parameters

None.

Example request

Response:

{
    "db": "VMart",
    "host": "10.20.100.247",
    "name": "v_vmart_node0001",
    "state": "UP"
}

18 - POST databases/:database_name/process

Creates a job to start the database identified by :database_name. The :database_name is the value of the name field that the GET databases command returns.

Returns a job ID that can be used to determine the status of the job. See GET jobs.

Resource URL

https://<NODE>:5444/databases/:database_name/process

The API key must have restricted level security or higher.

Parameters

Example request

An example of the full request using cURL:

curl -d "epoch=epoch_number&include=host1,host2" -X POST -H "VerticaApiKey: ValidAPIKey" https://<NODE>:5444/:testDB/process

Response:

{
    "id": "StartDatabase-testDB-2014-07-20 12:41:46.061408",
    "url": "/jobs/StartDatabase-testDB-2014-07-20 12:41:46.061408"
}

19 - GET databases/:database_name/process

Returns a state of UP or DOWN for the database identified by :database_name. The :database_name is the value of the namefield that the GET databases command returns.

Resource URL

https://<NODE>:5444/databases/:database_name/process

The API key must have restricted level security or higher.

Parameters

None.

Example request

Response:

{
    "state": "UP"
}

20 - DELETE databases/:database_name/process

Creates a job to stop the database identified by :database_name. The :database_name is the value of the name field that the GET databases command returns.

Returns a job ID that you can useto determine the status of the job. See GET jobs.

Resource URL

https://<NODE>:5444/databases/:database_name/process

The API key must have restricted level security or higher.

Parameters

Example request

An example of the full request using cURL:

curl -X DELETE -H "VerticaApiKey: ValidAPIKey" https://<NODE>:5444/:testDB/process?user_id=dbadmin"&"passwd=vertica

Response:

{
    "id": "StopDatabase-testDB-2014-07-20 12:46:04.406637",
    "url": "/jobs/StopDatabase-testDB-2014-07-20 12:46:04.406637"
}

21 - POST databases/:database_name/rebalance/process

Creates a job to run a rebalance on the database identified by host identified by :database_name. The :database_name is the value of the name field that the GET databases command returns.

Returns a job ID that you can use to determine the status of the job. See GET jobs.

Resource URL

https://<NODE>:5444/databases/:database_name/rebalance/process

The API key must have restricted level security or higher.

Parameters

Example request

Response:

{
    "id": "RebalanceData-testDB-2014-07-20 21:42:45.731038",
    "url": "/jobs/RebalanceData-testDB-2014-07-20 21:42:45.731038"
}

22 - POST databases/:database_name/Workload analyzer/process

Creates a job to run Workload Analyzer on the database identified by host identified by :database_name. The :database_name is the value of the name field that the GET databases command returns.

Returns a job ID that you can use to determine the status of the job. See GET jobs.

Resource URL

https://<NODE>:5444/databases/:database_name/Workload Analyzer/process

The API key must have restricted level security or higher.

Parameters

Example request

Response:

{
    "id": "AnalyzeWorkLoad-testDB-2014-07-20 21:48:27.972989",
    "url": "/jobs/AnalyzeWorkLoad-testDB-2014-07-20 21:48:27.972989"
}