689 lines
21 KiB
YAML
689 lines
21 KiB
YAML
openapi: 3.0.0
|
||
info:
|
||
title: SQL API
|
||
description: >
|
||
# Introduction
|
||
|
||
CARTO’s SQL API allows you to interact with your tables and data inside
|
||
CARTO, as if you were running SQL statements against a normal database.
|
||
|
||
|
||
You can execute single SQL statements or even a batch of long-running ones.
|
||
Refer to the SQL API guide to learn more.
|
||
|
||
# Authorization
|
||
|
||
In order to access SQL API you must provide an API key. The CARTO
|
||
Authorization guide explains how these keys are sent (TLDR: _HTTP basic
|
||
auth_ or _query string param_ with the API key token). Depending on the
|
||
permissions granted to the provided API key, the request will be authorized
|
||
or not.
|
||
version: 0.0.1
|
||
contact:
|
||
name: Have you found an error? Github issues
|
||
url: 'https://github.com/CartoDB/CartoDB-SQL-API/issues'
|
||
servers:
|
||
- url: 'https://{user}.{domain}/api/v2/'
|
||
description: Production server (uses live data)
|
||
variables:
|
||
domain:
|
||
default: carto.com
|
||
description: 'If on premise, change it to your domain'
|
||
user:
|
||
default: username
|
||
description: Your username
|
||
tags:
|
||
- name: Single SQL Statement
|
||
description: Run a single SQL statement
|
||
externalDocs:
|
||
url: 'http://doc.carto.com/pet-operations.htm'
|
||
- name: Batch Queries
|
||
description: >-
|
||
A Batch Queries Job enables you to request statements with long-running
|
||
CPU processing times
|
||
externalDocs:
|
||
url: 'http://doc.carto.com/pet-operations.htm'
|
||
paths:
|
||
/sql:
|
||
get:
|
||
summary: Run a single SQL statement using GET.
|
||
description: |
|
||
Runs a single SQL statement:
|
||
- SELECT, INSERT, UPDATE, DELETE,
|
||
- CREATE TABLE, ALTER TABLE, DROP TABLE
|
||
- CREATE INDEX
|
||
**NOTICE:** If the database detects an error when it's already streaming data the status code will be 200. Make sure to check if the *error* property is set in the response.
|
||
tags:
|
||
- Single SQL Statement
|
||
operationId: getSQLStatement
|
||
parameters:
|
||
- in: query
|
||
name: q
|
||
description: SQL statement
|
||
schema:
|
||
$ref: '#/components/schemas/SQLStatementString'
|
||
required: true
|
||
- in: query
|
||
name: filename
|
||
description: Output filename
|
||
schema:
|
||
type: string
|
||
required: false
|
||
- in: query
|
||
name: format
|
||
schema:
|
||
$ref: '#/components/schemas/OutputFormat'
|
||
required: false
|
||
responses:
|
||
'200':
|
||
description: Ok
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/StatementResult'
|
||
'400':
|
||
description: Bad Request
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/StatementErrorResult'
|
||
'401':
|
||
$ref: '#/components/responses/Unauthorized'
|
||
'403':
|
||
$ref: '#/components/responses/Forbidden'
|
||
'429':
|
||
$ref: '#/components/responses/PlatformLimits'
|
||
security:
|
||
- ApiKeyHTTPBasicAuth: []
|
||
- ApiKeyQueryParam: []
|
||
x-code-samples:
|
||
- lang: Curl
|
||
source: |
|
||
curl -X GET \
|
||
https://username.carto.com/api/v2/sql?q=SELECT count(*) FROM cities
|
||
post:
|
||
summary: Run a single SQL statement using POST.
|
||
description: >
|
||
Runs a single SQL statement:
|
||
|
||
- SELECT, INSERT, UPDATE, DELETE,
|
||
|
||
- CREATE TABLE, ALTER TABLE, DROP TABLE
|
||
|
||
- CREATE INDEX
|
||
|
||
|
||
Offers the same functionality as the GET endpoint. This version may come
|
||
handy when dealing with complex/long statments.
|
||
|
||
**NOTICE:** If the database detects an error when it's already streaming data the status code will be 200. Make sure to check if the *error* property is set in the response.
|
||
tags:
|
||
- Single SQL Statement
|
||
operationId: postSQLStatement
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
q:
|
||
$ref: '#/components/schemas/SQLStatementString'
|
||
filename:
|
||
type: string
|
||
description: Output filename
|
||
format:
|
||
$ref: '#/components/schemas/OutputFormat'
|
||
required:
|
||
- q
|
||
example:
|
||
q: SELECT count(*) FROM cities
|
||
filename: number_of_cities.json
|
||
responses:
|
||
'200':
|
||
description: Ok (Check `error` property)
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/StatementResult'
|
||
'400':
|
||
description: Bad Request
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/StatementErrorResult'
|
||
'401':
|
||
$ref: '#/components/responses/Unauthorized'
|
||
'403':
|
||
$ref: '#/components/responses/Forbidden'
|
||
'429':
|
||
$ref: '#/components/responses/PlatformLimits'
|
||
security:
|
||
- ApiKeyHTTPBasicAuth: []
|
||
- ApiKeyQueryParam: []
|
||
x-code-samples:
|
||
- lang: Curl
|
||
source: |
|
||
curl -X POST -H "Content-Type: application/json" -d '{ \
|
||
"q": "SELECT count(*) FROM cities", \
|
||
"filename": "number_of_cities.json" \
|
||
}' "https://username.carto.com/api/v2/sql"
|
||
|
||
/sql/copyfrom:
|
||
post:
|
||
summary: Runs a copy command to ingest data
|
||
description: |
|
||
Runs a single COPY command:
|
||
- COPY mytable (col1, col2) FROM stdin WITH (FORMAT CSV)
|
||
tags:
|
||
- Single COPY command
|
||
operationId: postCopyFromStatement
|
||
parameters:
|
||
- in: query
|
||
name: q
|
||
description: COPY statement
|
||
schema:
|
||
$ref: '#/components/schemas/SQLStatementString'
|
||
required: true
|
||
example: COPY upload_example (the_geom,name,age) FROM stdin WITH (FORMAT csv,HEADER true)
|
||
- in: header
|
||
name: Transfer-Encoding
|
||
schema:
|
||
type: string
|
||
enum:
|
||
- chunked
|
||
required: true
|
||
- in: header
|
||
name: Content-Encoding
|
||
schema:
|
||
type: string
|
||
enum:
|
||
- gzip
|
||
required: false
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/octet-stream:
|
||
schema:
|
||
type: string
|
||
|
||
responses:
|
||
'200':
|
||
description: Ok
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/CopyFromStatement'
|
||
'401':
|
||
$ref: '#/components/responses/Unauthorized'
|
||
'403':
|
||
$ref: '#/components/responses/Forbidden'
|
||
'429':
|
||
$ref: '#/components/responses/PlatformLimits'
|
||
security:
|
||
- ApiKeyHTTPBasicAuth: []
|
||
- ApiKeyQueryParam: []
|
||
x-code-samples:
|
||
- lang: Curl
|
||
source: |
|
||
curl -X POST -H 'Content-Encoding: gzip' -H 'Transfer-Encoding: chunked' -H 'Content-Type: application/octet-stream' --data-binary @upload_example.csv.gz 'http://{username}.carto.com/api/v2/sql/copyfrom?q=COPY upload_example (the_geom,name,age) FROM stdin WITH (FORMAT csv,HEADER true)&api_key={api_key}'
|
||
|
||
/sql/copyto:
|
||
get:
|
||
summary: Runs a copy command to extract data
|
||
description: |
|
||
Runs a single COPY command:
|
||
- COPY mytable TO stdout WITH (FORMAT CSV)
|
||
tags:
|
||
- Single COPY command
|
||
operationId: getCopyToStatement
|
||
parameters:
|
||
- in: query
|
||
name: q
|
||
description: COPY statement
|
||
schema:
|
||
$ref: '#/components/schemas/SQLStatementString'
|
||
required: true
|
||
- in: query
|
||
name: filename
|
||
description: Sets the content-disposition file name header
|
||
schema:
|
||
type: string
|
||
required: false
|
||
responses:
|
||
'200':
|
||
description: Ok.
|
||
content:
|
||
application/octet-stream:
|
||
schema:
|
||
type: string
|
||
'401':
|
||
$ref: '#/components/responses/Unauthorized'
|
||
'403':
|
||
$ref: '#/components/responses/Forbidden'
|
||
'429':
|
||
$ref: '#/components/responses/PlatformLimits'
|
||
security:
|
||
- ApiKeyHTTPBasicAuth: []
|
||
- ApiKeyQueryParam: []
|
||
x-code-samples:
|
||
- lang: Curl
|
||
source: |
|
||
curl --output upload_example_dl.csv --compressed "http://{username}.carto.com/api/v2/sql/copyto?q=COPY upload_example (the_geom,name,age) TO stdout WITH(FORMAT csv,HEADER true)&api_key={api_key}"
|
||
|
||
/sql/job:
|
||
post:
|
||
summary: Create a Job
|
||
description: Creates a Batch Queries Job
|
||
tags:
|
||
- Batch Queries
|
||
operationId: createJob
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/CreateJobQueryField'
|
||
responses:
|
||
'200':
|
||
description: Ok
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/Job'
|
||
example:
|
||
job_id: de305d54-75b4-431b-adb2-eb6b9e546014
|
||
user: username
|
||
status: pending
|
||
query: UPDATE nasdaq SET price = '$101.00' WHERE company = 'CARTO'
|
||
created_at: '2017-12-15T07:36:25Z'
|
||
updated_at: '2017-12-15T07:36:25Z'
|
||
'401':
|
||
$ref: '#/components/responses/Unauthorized'
|
||
'403':
|
||
$ref: '#/components/responses/Forbidden'
|
||
'429':
|
||
$ref: '#/components/responses/PlatformLimits'
|
||
security:
|
||
- ApiKeyHTTPBasicAuth: []
|
||
- ApiKeyQueryParam: []
|
||
x-code-samples:
|
||
- lang: Curl
|
||
source: |
|
||
curl -X POST -H "Content-Type: application/json" -d '{ \
|
||
"query": "UPDATE nasdaq SET price = '$101.00' WHERE company = 'CARTO'", \
|
||
}' "https://username.carto.com/api/v2/sql/job"
|
||
|
||
'/sql/job/{job_id}':
|
||
parameters:
|
||
- $ref: '#/components/parameters/jobId'
|
||
get:
|
||
summary: Get a Job
|
||
description: Returns a Batch Queries Job based on it's ID.
|
||
tags:
|
||
- Batch Queries
|
||
operationId: getJob
|
||
responses:
|
||
'200':
|
||
description: Ok
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/Job'
|
||
example:
|
||
job_id: de305d54-75b4-431b-adb2-eb6b9e546014
|
||
user: username
|
||
status: pending
|
||
query: UPDATE nasdaq SET price = '$101.00' WHERE company = 'CARTO'
|
||
created_at: '2017-12-15T07:36:25Z'
|
||
updated_at: '2017-12-15T07:36:25Z'
|
||
'401':
|
||
$ref: '#/components/responses/Unauthorized'
|
||
'403':
|
||
$ref: '#/components/responses/Forbidden'
|
||
'404':
|
||
$ref: '#/components/responses/NotFound'
|
||
'429':
|
||
$ref: '#/components/responses/PlatformLimits'
|
||
security:
|
||
- ApiKeyHTTPBasicAuth: []
|
||
- ApiKeyQueryParam: []
|
||
x-code-samples:
|
||
- lang: Curl
|
||
source: >
|
||
curl -X GET \
|
||
|
||
https://username.carto.com/api/v2/sql/job/de305d54-75b4-431b-adb2-eb6b9e546014
|
||
put:
|
||
summary: Update a Job
|
||
description: |
|
||
Updates the query of a Batch Queries Job.
|
||
|
||
**Notice:** Only the _query_ property can be updated
|
||
tags:
|
||
- Batch Queries
|
||
operationId: updateJob
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/CreateJobQueryField'
|
||
example:
|
||
q: UPDATE nasdaq SET price = '$999.00' WHERE company = 'CARTO'
|
||
responses:
|
||
'200':
|
||
description: Ok
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/Job'
|
||
example:
|
||
job_id: de305d54-75b4-431b-adb2-eb6b9e546014
|
||
user: username
|
||
status: pending
|
||
query: UPDATE nasdaq SET price = '999.00' WHERE company = 'CARTO'
|
||
created_at: '2017-12-15T07:36:25Z'
|
||
updated_at: '2017-12-16T12:52:13Z'
|
||
'401':
|
||
$ref: '#/components/responses/Unauthorized'
|
||
'403':
|
||
$ref: '#/components/responses/Forbidden'
|
||
'404':
|
||
$ref: '#/components/responses/NotFound'
|
||
'429':
|
||
$ref: '#/components/responses/PlatformLimits'
|
||
security:
|
||
- ApiKeyHTTPBasicAuth: []
|
||
- ApiKeyQueryParam: []
|
||
x-code-samples:
|
||
- lang: Curl
|
||
source: >
|
||
curl -X PUT -H "Content-Type: application/json" -d '{ \
|
||
"query": "UPDATE nasdaq SET price = '$999.00' WHERE company = 'CARTO'", \
|
||
}'
|
||
"https://username.carto.com/api/v2/sql/job/de305d54-75b4-431b-adb2-eb6b9e546014"
|
||
delete:
|
||
summary: Cancel a Job
|
||
description: >
|
||
Canceles a Batch Queries Job based on it's ID. The Job doesn't get
|
||
deleted, just it's status is set as _canceled_.
|
||
|
||
Only jobs whose status are _pending_ or _running_ can be canceled.
|
||
|
||
* **pending**: the job will never be executed
|
||
|
||
* **running**: the job will be terminated immediately
|
||
tags:
|
||
- Batch Queries
|
||
operationId: cancelJob
|
||
responses:
|
||
'200':
|
||
description: Ok
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/Job'
|
||
example:
|
||
job_id: de305d54-75b4-431b-adb2-eb6b9e546014
|
||
user: username
|
||
status: canceled
|
||
query: UPDATE nasdaq SET price = '999.00' WHERE company = 'CARTO'
|
||
created_at: '2017-12-15T07:36:25Z'
|
||
updated_at: '2017-12-16T12:52:13Z'
|
||
'401':
|
||
$ref: '#/components/responses/Unauthorized'
|
||
'403':
|
||
$ref: '#/components/responses/Forbidden'
|
||
'404':
|
||
$ref: '#/components/responses/NotFound'
|
||
'429':
|
||
$ref: '#/components/responses/PlatformLimits'
|
||
security:
|
||
- ApiKeyHTTPBasicAuth: []
|
||
- ApiKeyQueryParam: []
|
||
x-code-samples:
|
||
- lang: Curl
|
||
source: >
|
||
curl -X DELETE \
|
||
|
||
https://username.carto.com/api/v2/sql/job/de305d54-75b4-431b-adb2-eb6b9e546014
|
||
components:
|
||
schemas:
|
||
CopyFromStatement:
|
||
type: object
|
||
properties:
|
||
time:
|
||
type: number
|
||
format: float
|
||
description: time in seconds it has taken to run the statement
|
||
total_rows:
|
||
type: number
|
||
format: integer
|
||
description: number of rows copied into the database
|
||
example:
|
||
time: 2.3
|
||
total_rows: 142012
|
||
StatementResult:
|
||
type: object
|
||
properties:
|
||
error:
|
||
type: array
|
||
items:
|
||
type: string
|
||
description: [Optional] List of errors produced by the query. If this property is present, the query has failed.
|
||
time:
|
||
type: number
|
||
format: float
|
||
description: time in seconds it has taken to run the statement
|
||
total_rows:
|
||
type: number
|
||
format: integer
|
||
description: number of rows returned
|
||
rows:
|
||
type: array
|
||
items:
|
||
type: object
|
||
description: the structure/data depends on the statement
|
||
example:
|
||
time: 0.007
|
||
total_rows: 1
|
||
rows:
|
||
- count: 4994
|
||
StatementErrorResult:
|
||
type: object
|
||
properties:
|
||
error:
|
||
type: array
|
||
items:
|
||
type: string
|
||
description: List of errors produced by the query.
|
||
hint:
|
||
type: string
|
||
description: [Optional] Hint about the errors
|
||
example:
|
||
error: ["function st_buffer(geometry) does not exist"]
|
||
hint: No function matches the given name and argument types. You might need to add explicit type casts
|
||
Job:
|
||
allOf:
|
||
- $ref: '#/components/schemas/SQLGeneralStatment'
|
||
- type: object
|
||
properties:
|
||
job_id:
|
||
type: string
|
||
format: uuid
|
||
description: a Job's universally unique identifier (uuid).
|
||
user:
|
||
type: string
|
||
description: 'user identifier, as displayed by the username.'
|
||
status:
|
||
$ref: '#/components/schemas/JobStatus'
|
||
failed_reason:
|
||
description: 'displays the database error message, if something went wrong.'
|
||
type: string
|
||
- $ref: '#/components/schemas/Timestamps'
|
||
example:
|
||
job_id: de305d54-75b4-431b-adb2-eb6b9e546014
|
||
user: username
|
||
status: pending
|
||
query: UPDATE nasdaq SET price = '$101.00' WHERE company = 'CARTO'
|
||
created_at: '2017-12-15T07:36:25Z'
|
||
updated_at: '2017-12-15T07:36:25Z'
|
||
OutputFormat:
|
||
title: Output format
|
||
type: string
|
||
enum:
|
||
- GPKG
|
||
- CSV
|
||
- SHP
|
||
- SVG
|
||
- KML
|
||
- SpatiaLite
|
||
- GeoJSON
|
||
description: Output format
|
||
JobStatus:
|
||
title: Job status
|
||
type: string
|
||
enum:
|
||
- pending
|
||
- running
|
||
- done
|
||
- failed
|
||
- canceled
|
||
- unknown
|
||
description: displays the result of the long-running statement
|
||
SQLStatementString:
|
||
title: SQL statement
|
||
type: string
|
||
SQLSingleStatement:
|
||
type: object
|
||
properties:
|
||
query:
|
||
$ref: '#/components/schemas/SQLStatementString'
|
||
required:
|
||
- query
|
||
CreateJobQueryField:
|
||
type: object
|
||
properties:
|
||
query:
|
||
oneOf:
|
||
- $ref: '#/components/schemas/SQLStatementString'
|
||
- $ref: '#/components/schemas/ArrayOfSQLStatements'
|
||
- $ref: '#/components/schemas/CreateJobQueryFieldWithFallbacks'
|
||
description: long-running SQL statement(s).
|
||
required:
|
||
- query
|
||
example:
|
||
query: UPDATE nasdaq SET price = '$101.00' WHERE company = 'CARTO'
|
||
ArrayOfSQLStatements:
|
||
title: Array of SQL statements
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/SQLStatementString'
|
||
CreateJobQueryFieldWithFallbacks:
|
||
title: Array of SQL statements with Fallbacks
|
||
allOf:
|
||
- $ref: '#/components/schemas/Fallbacks'
|
||
- type: object
|
||
properties:
|
||
query:
|
||
type: array
|
||
items:
|
||
allOf:
|
||
- type: object
|
||
properties:
|
||
query:
|
||
$ref: '#/components/schemas/SQLStatementString'
|
||
- $ref: '#/components/schemas/Fallbacks'
|
||
required:
|
||
- query
|
||
SQLMultipleStatements:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/StatementAndStatus'
|
||
SQLMultipleStatementsWithFallbacks:
|
||
allOf:
|
||
- type: object
|
||
properties:
|
||
query:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/StatementAndStatusAndFallbacks'
|
||
- $ref: '#/components/schemas/Fallbacks'
|
||
StatementAndStatus:
|
||
title: SQL statement and status
|
||
type: object
|
||
properties:
|
||
query:
|
||
$ref: '#/components/schemas/SQLStatementString'
|
||
status:
|
||
$ref: '#/components/schemas/JobStatus'
|
||
StatementAndStatusAndFallbacks:
|
||
allOf:
|
||
- $ref: '#/components/schemas/StatementAndStatus'
|
||
- $ref: '#/components/schemas/Fallbacks'
|
||
Fallbacks:
|
||
type: object
|
||
properties:
|
||
onsuccess:
|
||
$ref: '#/components/schemas/SQLStatementString'
|
||
onerror:
|
||
$ref: '#/components/schemas/SQLStatementString'
|
||
SQLGeneralStatment:
|
||
type: object
|
||
properties:
|
||
query:
|
||
oneOf:
|
||
- $ref: '#/components/schemas/SQLStatementString'
|
||
- $ref: '#/components/schemas/SQLMultipleStatements'
|
||
- $ref: '#/components/schemas/SQLMultipleStatementsWithFallbacks'
|
||
description: long-running SQL statement(s).
|
||
JobQueryField:
|
||
type: object
|
||
properties:
|
||
query:
|
||
oneOf:
|
||
- $ref: '#/components/schemas/SQLStatementString'
|
||
- $ref: '#/components/schemas/SQLMultipleStatements'
|
||
Timestamps:
|
||
type: object
|
||
properties:
|
||
created_at:
|
||
type: string
|
||
format: date-time
|
||
description: the date and time when the job schema was created
|
||
updated_at:
|
||
type: string
|
||
format: date-time
|
||
description: >-
|
||
the date and time of when the job schema was last updated, or
|
||
modified.
|
||
securitySchemes:
|
||
ApiKeyHTTPBasicAuth:
|
||
type: http
|
||
scheme: basic
|
||
ApiKeyQueryParam:
|
||
type: apiKey
|
||
in: header
|
||
name: api_key
|
||
parameters:
|
||
jobId:
|
||
in: path
|
||
name: job_id
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
description: the job universally unique identifier (uuid).
|
||
responses:
|
||
NotFound:
|
||
description: The specified resource was not found
|
||
Unauthorized:
|
||
description: Unauthorized. No authentication provided.
|
||
Forbidden:
|
||
description: Forbidden. The API key does not authorize this request.
|
||
BadInput:
|
||
description: Request's parameters error
|
||
PlatformLimits:
|
||
description: You are over platform's limits.
|