Admin REST API
Overview
The Admin REST API is a secondary API provided by the Query service. This API enables you to retrieve statistics about the clusters and nodes running the Query service; view or specify service-level settings; and view or delete requests.
The API schemes and host URLs are as follows:
-
http://node:8093/
-
https://node:18093/
(for secure access)
where node
is the host name or IP address of a computer running the N1QL query engine.
Paths
GET /admin/clusters
Responses
HTTP Code | Description | Schema |
---|---|---|
200 |
An array of objects, each of which gives information about one cluster. |
< Clusters > array |
GET /admin/clusters/{cluster}
Responses
HTTP Code | Description | Schema |
---|---|---|
200 |
An object giving information about the specified cluster. |
GET /admin/clusters/{cluster}/nodes
Responses
HTTP Code | Description | Schema |
---|---|---|
200 |
An array of objects, each of which gives information about one node. |
< Nodes > array |
GET /admin/clusters/{cluster}/nodes/{node}
Parameters
Type | Name | Description | Schema |
---|---|---|---|
Path |
cluster |
The name of a cluster. |
string |
Path |
node |
The name of a node. |
string |
GET /admin/config
GET /admin/prepareds
Responses
HTTP Code | Description | Schema |
---|---|---|
200 |
An array of objects, each of which contains information about one prepared statement. |
< Statements > array |
GET /admin/prepareds/{name}
Description
Returns the specified prepared statement.
Refer to Get Prepared Statements for examples. |
Parameters
Type | Name | Description | Schema |
---|---|---|---|
Path |
name |
The name of a prepared statement. This may be a UUID that was assigned automatically, or a name that was user-specified when the statement was created. |
string |
Responses
HTTP Code | Description | Schema |
---|---|---|
200 |
An object containing information about the specified prepared statement. |
DELETE /admin/prepareds/{name}
Description
Deletes the specified prepared statement.
Refer to Delete Prepared Statements for examples. |
Parameters
Type | Name | Description | Schema |
---|---|---|---|
Path |
name |
The name of a prepared statement. This may be a UUID that was assigned automatically, or a name that was user-specified when the statement was created. |
string |
Responses
HTTP Code | Description | Schema |
---|---|---|
200 |
True if the prepared statement was successfully deleted. |
boolean |
500 |
Returns an error message if the prepared statement could not be found. |
object |
GET /admin/active_requests
Responses
HTTP Code | Description | Schema |
---|---|---|
200 |
An array of objects, each of which contains information about one active request. |
< Requests > array |
GET /admin/active_requests/{request}
Parameters
Type | Name | Description | Schema |
---|---|---|---|
Path |
request |
The name of a request.
This is the |
string |
Responses
HTTP Code | Description | Schema |
---|---|---|
200 |
An object containing information about the specified active request. |
DELETE /admin/active_requests/{request}
Description
Terminates the specified active query request.
Refer to Terminate an Active Request for examples. |
Parameters
Type | Name | Description | Schema |
---|---|---|---|
Path |
request |
The name of a request.
This is the |
string |
Responses
HTTP Code | Description | Schema |
---|---|---|
200 |
True if the active request was successfully terminated. |
boolean |
500 |
Returns an error message if the active request could not be found. |
object |
GET /admin/completed_requests
Responses
HTTP Code | Description | Schema |
---|---|---|
200 |
An array of objects, each of which contains information about one completed request. |
< Requests > array |
GET /admin/completed_requests/{request}
Parameters
Type | Name | Description | Schema |
---|---|---|---|
Path |
request |
The name of a request.
This is the |
string |
Responses
HTTP Code | Description | Schema |
---|---|---|
200 |
An object containing information about the specified active request. |
DELETE /admin/completed_requests/{request}
Description
Purges the specified completed request.
Refer to Purge the Completed Requests for examples. |
Parameters
Type | Name | Description | Schema |
---|---|---|---|
Path |
request |
The name of a request.
This is the |
string |
Responses
HTTP Code | Description | Schema |
---|---|---|
200 |
True if the completed request was successfully purged. |
boolean |
500 |
Returns an error message if the completed request could not be found. |
object |
GET /admin/indexes/prepareds
Description
Returns all prepared index statements.
|
Responses
HTTP Code | Description | Schema |
---|---|---|
200 |
An array of strings, each of which is the name of a prepared index statement. |
< string > array |
GET /admin/indexes/active_requests
Description
Returns all active index requests.
|
Responses
HTTP Code | Description | Schema |
---|---|---|
200 |
An array of strings, each of which is the requestID of an active index request. |
< string (uuid) > array |
GET /admin/indexes/completed_requests
Description
Returns all completed index requests.
|
Responses
HTTP Code | Description | Schema |
---|---|---|
200 |
An array of strings, each of which is the requestID of a completed index request. |
< string (uuid) > array |
GET /admin/vitals
Description
Returns data about the running state and health of the query engine. This information can be very useful to assess the current workload and performance characteristics of a query engine, and hence load-balance the requests being sent to various query engines.
Refer to Get System Vitals for examples. |
GET /admin/stats
Responses
HTTP Code | Description | Schema |
---|---|---|
200 |
An object containing all statistics. Each statistic consist of a top-level statistic name and a metric name. Each statistic has a different set of metrics. |
GET /admin/stats/{stat}
Parameters
Type | Name | Description | Schema |
---|---|---|---|
Path |
stat |
The name of a statistic. Only top-level statistic names can be used. You cannot specify a metric. |
enum (active_requests, at_plus, cancelled, deletes, errors, inserts, invalid_requests, mutations, prepared, queued_requests, request_rate, request_time, request_timer, requests, requests_1000ms, requests_250ms, requests_5000ms, requests_500ms, result_count, result_size, scan_plus, selects, service_time, unbounded, updates, warnings) |
Responses
HTTP Code | Description | Schema |
---|---|---|
200 |
An object containing all metrics for the specified statistic. Each statistic has a different set of metrics. |
GET /debug/vars
Responses
HTTP Code | Description | Schema |
---|---|---|
302 |
Redirects to the GET /admin/stats endpoint. |
text/html |
GET /admin/settings
Description
Returns service-level query settings.
Refer to Query Settings for more information and examples. |
POST /admin/settings
Description
Updates service-level query settings.
Refer to Query Settings for more information and examples. |
Parameters
Type | Name | Description | Schema |
---|---|---|---|
Body |
Settings |
An object specifying service-level query settings. |
Responses
HTTP Code | Description | Schema |
---|---|---|
200 |
An object giving service-level query settings, including the latest changes. |
Definitions
Clusters
Name | Description | Schema |
---|---|---|
accountstore |
The URL of the accountstore. |
string |
configstore |
The URL of the configstore. |
string |
datastore |
The URL of the datastore. |
string |
name |
The name of the cluster. |
string |
version |
string |
Nodes
Name | Description | Schema |
---|---|---|
adminEndpoint |
The HTTP URL of the admin endpoint. |
string |
adminSecure |
The HTTPS URL of the admin endpoint. |
string |
cluster |
The name of the cluster. |
string |
name |
The URL of the node, including port number. |
string |
options |
string |
|
queryEndpoint |
The HTTP URL of the query endpoint. |
string |
querySecure |
The HTTPS URL of the query endpoint. |
string |
Requests
Name | Description | Schema |
---|---|---|
clientContextID |
The opaque ID or context provided by the client. |
string (uuid) |
elapsedTime |
The time taken from when the request was acknowledged by the service to when the request was completed. It includes the time taken by the service to schedule the request. |
string (duration) |
errorCount |
Total number of errors encountered while executing the query. |
integer |
phaseCounts |
Count of documents processed at selective phases involved in the query execution. Refer to Attribute Profile in Query Response for more details and examples. |
object |
phaseOperators |
Indicates the number of each kind of query operators involved in different phases of the query processing. Refer to Attribute Profile in Query Response for more details and examples. |
object |
remoteAddr |
IP address and port number of the client application, from where the query is received. |
string |
requestId |
Unique request ID internally generated for the query. |
string (uuid) |
requestTime |
Timestamp when the query is received. |
string (date-time) |
resultCount |
Total number of documents returned in the query result. |
integer |
resultSize |
Total number of bytes returned in the query result. |
integer |
scanConsistency |
The value of the query setting Scan Consistency used for the query. |
string |
serviceTime |
Total amount of calendar time taken to complete the query. |
string (duration) |
state |
The state of the query execution, such as completed, running, cancelled. |
string |
statement |
The N1QL query statement being executed. |
string |
userAgent |
Name of the client application or program that issued the query. |
string |
users |
Username with whose privileges the query is run. |
string |
Statements
Name | Description | Schema |
---|---|---|
avgElapsedTime |
The mean time taken from when the request to execute the prepared statement was acknowledged by the service, to when the request was completed. It includes the time taken by the service to schedule the request. This property is only returned when the prepared statement has been executed. It is only returned when retrieving a specific prepared statement, not when retrieving all prepared statements. |
string (duration) |
avgServiceTime |
The mean amount of calendar time taken to complete the execution of the prepared statement. This property is only returned when the prepared statement has been executed. It is only returned when retrieving a specific prepared statement, not when retrieving all prepared statements. |
string (duration) |
encoded_plan |
The full prepared statement in encoded format. |
string |
featureControls |
This property is provided for technical support only. It is only returned when retrieving a specific prepared statement, not when retrieving all prepared statements. |
integer |
indexApiVersion |
This property is provided for technical support only. It is only returned when retrieving a specific prepared statement, not when retrieving all prepared statements. |
integer |
lastUse |
Date and time of last use. This property is only returned when the prepared statement has been executed. |
string (date-time) |
maxElapsedTime |
The maximum time taken from when the request to execute the prepared statement was acknowledged by the service, to when the request was completed. It includes the time taken by the service to schedule the request. This property is only returned when the prepared statement has been executed. It is only returned when retrieving a specific prepared statement, not when retrieving all prepared statements. |
string (duration) |
maxServiceTime |
The maximum amount of calendar time taken to complete the execution of the prepared statement. This property is only returned when the prepared statement has been executed. It is only returned when retrieving a specific prepared statement, not when retrieving all prepared statements. |
string (duration) |
minElapsedTime |
The minimum time taken from when the request to execute the prepared statement was acknowledged by the service, to when the request was completed. It includes the time taken by the service to schedule the request. This property is only returned when the prepared statement has been executed. It is only returned when retrieving a specific prepared statement, not when retrieving all prepared statements. |
string (duration) |
minServiceTime |
The minimum amount of calendar time taken to complete the execution of the prepared statement. This property is only returned when the prepared statement has been executed. It is only returned when retrieving a specific prepared statement, not when retrieving all prepared statements. |
string (duration) |
name |
The name of the prepared statement. This may be a UUID that was assigned automatically, or a name that was user-specified when the statement was created. |
string |
statement |
The text of the N1QL query. |
string |
uses |
The count of times the prepared statement has been executed. |
integer |
Vitals
Name | Description | Schema |
---|---|---|
cores |
The maximum number of logical cores available to the query engine. |
integer |
cpu.sys.percent |
CPU usage. The percentage of time spent executing system code since the last time the statistics were checked. |
integer (int64) |
cpu.user.percent |
CPU usage. The percentage of time spent executing user code since the last time the statistics were checked. |
integer (int64) |
gc.num |
The target heap size of the next garbage collection cycle. |
integer (int64) |
gc.pause.percent |
The percentage of time spent pausing for garbage collection since the last time the statistics were checked. |
integer (int64) |
gc.pause.time |
The total time spent pausing for garbage collection since the query engine started (ns). |
string (duration) |
local.time |
The local time of the query engine. |
string (date-time) |
memory.system |
The total amount of memory obtained from the operating system (bytes). This measures the virtual address space reserved by the query engine for heaps, stacks, and other internal data structures. |
integer (int64) |
memory.total |
The cumulative amount of memory allocated for heap objects (bytes). This increases as heap objects are allocated, but does not decrease when objects are freed. |
integer (int64) |
memory.usage |
The amount of memory allocated for heap objects (bytes). This increases as heap objects are allocated, and decreases as objects are freed. |
integer (int64) |
request.active.count |
Total number of active requests. |
integer |
request.completed.count |
Total number of completed requests. |
integer |
request.per.sec.15min |
Number of N1QL requests processed per second. 15-minute exponentially weighted moving average. |
number |
request.per.sec.1min |
Number of N1QL requests processed per second. 1-minute exponentially weighted moving average. |
number |
request.per.sec.5min |
Number of N1QL requests processed per second. 5-minute exponentially weighted moving average. |
number |
request.prepared.percent |
Percentage of requests that are prepared statements. |
integer |
request_time.80percentile |
End-to-end time to process a query. The 80th percentile. |
string (duration) |
request_time.95percentile |
End-to-end time to process a query. The 95th percentile. |
string (duration) |
request_time.99percentile |
End-to-end time to process a query. The 99th percentile. |
string (duration) |
request_time.mean |
End-to-end time to process a query. The mean value. |
string (duration) |
request_time.median |
End-to-end time to process a query. The median value. |
string (duration) |
total.threads |
The number of active threads used by the query engine. |
integer |
uptime |
The uptime of the query engine. |
string (duration) |
version |
The version of the query engine. |
string |
Statistics
Name | Description | Schema |
---|---|---|
active_requests.count |
Total number of active requests. |
integer |
at_plus.count |
Total number of N1QL requests with |
integer |
cancelled.count |
Total number of cancelled requests. |
integer |
deletes.count |
Total number of DELETE operations. |
integer |
errors.count |
The total number of N1QL errors returned so far. |
integer |
inserts.count |
Total number of INSERT operations. |
integer |
invalid_requests.count |
Total number of requests for unsupported endpoints. |
integer |
mutations.count |
Total number of document mutations. |
integer |
prepared.15m.rate |
Prepared statements executed per second. 15-minute exponentially weighted moving average. |
number |
prepared.1m.rate |
Prepared statements executed per second. 1-minute exponentially weighted moving average. |
number |
prepared.5m.rate |
Prepared statements executed per second. 5-minute exponentially weighted moving average. |
number |
prepared.count |
Total number of prepared statements executed. |
integer |
prepared.mean.rate |
Prepared statements executed per second. Mean rate since the query service started. |
number |
queued_requests.count |
Total number of queued requests. |
integer |
request_rate.15m.rate |
Number of N1QL requests processed per second. 15-minute exponentially weighted moving average. |
integer |
request_rate.1m.rate |
Number of N1QL requests processed per second. 1-minute exponentially weighted moving average. |
integer |
request_rate.5m.rate |
Number of N1QL requests processed per second. 5-minute exponentially weighted moving average. |
integer |
request_rate.count |
Total number of N1QL requests. |
integer |
request_rate.mean.rate |
Number of N1QL requests processed per second. Mean rate since the query service started. |
number |
request_time.count |
Total end-to-end time to process all queries (ns). |
integer |
request_timer.15m.rate |
Number of N1QL requests processed per second. 15-minute exponentially weighted moving average. |
number |
request_timer.1m.rate |
Number of N1QL requests processed per second. 1-minute exponentially weighted moving average. |
number |
request_timer.5m.rate |
Number of N1QL requests processed per second. 5-minute exponentially weighted moving average. |
number |
request_timer.75% |
End-to-end time to process a query (ns). The 75th percentile. |
number |
request_timer.95% |
End-to-end time to process a query (ns). The 95th percentile. |
number |
request_timer.99% |
End-to-end time to process a query (ns). The 99th percentile. |
number |
request_timer.99.9% |
End-to-end time to process a query (ns). The 99.9th percentile. |
number |
request_timer.count |
Total number of N1QL requests. |
integer |
request_timer.max |
End-to-end time to process a query (ns). The maximum value. |
integer |
request_timer.mean |
End-to-end time to process a query (ns). The mean value. |
number |
request_timer.mean.rate |
Number of N1QL requests processed per second. Mean rate since the query service started. |
number |
request_timer.median |
End-to-end time to process a query (ns). The median value. |
number |
request_timer.min |
End-to-end time to process a query (ns). The minimum value. |
integer |
request_timer.stddev |
End-to-end time to process a query (ns). The standard deviation. |
number |
requests.count |
Total number of N1QL requests. |
integer |
requests_1000ms.count |
Number of queries that take longer than 1000ms. |
integer |
requests_250ms.count |
Number of queries that take longer than 250ms. |
integer |
requests_5000ms.count |
Number of queries that take longer than 5000ms. |
integer |
requests_500ms.count |
Number of queries that take longer than 500ms. |
integer |
result_count.count |
Total number of results (documents) returned by the query engine. |
integer |
result_size.count |
Total size of data returned by the query engine (bytes). |
integer |
scan_plus.count |
Total number of N1QL requests with |
integer |
selects.count |
Total number of SELECT requests. |
integer |
service_time.count |
Time to execute all queries (ns). |
integer |
unbounded.count |
Total number of N1QL requests with |
integer |
updates.count |
Total number of UPDATE requests. |
integer |
warnings.count |
The total number of N1QL warnings returned so far. |
integer |
Metrics
Name | Description | Schema |
---|---|---|
15m.rate |
15-minute exponentially weighted moving average. |
number |
1m.rate |
1-minute exponentially weighted moving average. |
number |
5m.rate |
5-minute exponentially weighted moving average. |
number |
75% |
The 75th percentile. |
number |
95% |
The 95th percentile. |
number |
99% |
The 99th percentile. |
number |
99.9% |
The 99.9th percentile. |
number |
count |
A single value that represents the current state. |
integer |
max |
The maximum value. |
integer |
mean |
The mean value. |
number |
mean.rate |
Mean rate since the query service started. |
number |
median |
The median value. |
number |
min |
The minimum value. |
integer |
stddev |
The standard deviation. |
number |
Settings
Name | Description | Schema |
---|---|---|
completed-limit |
Maximum number of completed requests.
As new completed requests are added, old ones are removed.
Refer to Configure the Completed Requests for more information and examples. |
integer (int32) |
completed-threshold |
A duration in milliseconds.
All completed queries lasting longer than this threshold are logged in the completed requests catalog.
Refer to Configure the Completed Requests for more information and examples. |
integer (int32) |
controls |
Specifies if there should be a controls section returned with the request results. |
boolean |
cpuprofile |
The absolute path and filename to write the CPU profile to a local file. |
string |
debug |
Use debug mode. |
boolean |
keep-alive-length |
Maximum size of buffered result. |
integer (int32) |
loglevel |
Log level used in the logger. |
enum (DEBUG, TRACE, INFO, WARN, ERROR, SEVERE, NONE) |
max-index-api |
Max index API. This setting is provided for technical support only. |
integer (int32) |
max-parallelism |
Maximum number of index partitions, for computing aggregation in parallel.
Refer to Max Parallelism for more information. |
integer (int32) |
memprofile |
Filename to write the diagnostic memory usage log. |
string |
n1ql-feat-ctrl |
N1QL feature control. This setting is provided for technical support only. |
integer (int32) |
pipeline-batch |
Controls the number of items execution operators can batch for Fetch from the KV. |
integer (int32) |
pipeline-cap |
Maximum number of items each execution operator can buffer between various operators. |
integer (int32) |
prepared-limit |
Maximum number of prepared statements in the cache. |
integer (int32) |
pretty |
Specifies whether query results are returned in pretty format. |
boolean |
profile |
Specifies if there should be a profile section returned with the request results.
Refer to Monitoring and Profiling Details for more information and examples. |
enum (off, phases, timings) |
request-size-cap |
Maximum size of a request. |
integer (int32) |
scan-cap |
Maximum buffered channel size between the indexer client and the query service for index scans.
This parameter controls when to use scan backfill. |
integer (int32) |
servicers |
The number of service threads for the query. |
integer (int32) |
timeout |
Maximum time to spend on the request before timing out. |
string (duration) |
Security
Default
The Admin API supports admin credentials. Credentials can be passed via HTTP headers (HTTP basic authentication).
Type : basic
None
No authentication is required for the GET /admin/ping or GET /debug/vars endpoints.
Type : basic