docs 781 applied to sql api docs
This commit is contained in:
csobier
parent
3a3c49e40d
commit
bfcf5487f7
@ -1,6 +1,6 @@
|
||||
# SQL API
|
||||
|
||||
CartoDB's SQL API allows you to interact with your tables and data inside CartoDB, as if you were running SQL statements against a normal database. The database behind CartoDB is PostgreSQL so if you need help with specific SQL statements or you want to learn more about it, visit the [official documentation](http://www.postgresql.org/docs/9.1/static/sql.html).
|
||||
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. The database behind Carto is PostgreSQL so if you need help with specific SQL statements or you want to learn more about it, visit the [official documentation](http://www.postgresql.org/docs/9.1/static/sql.html).
|
||||
|
||||
There are two main situations in which you would want to use the SQL API:
|
||||
|
||||
|
||||
@ -1,17 +1,17 @@
|
||||
# Authentication
|
||||
|
||||
For all access to private tables, and for write access to public tables, CartoDB enforces secure API access that requires you to authorize your queries. In order to authorize queries, you can use an API Key or a Consumer Key.
|
||||
For all access to private tables, and for write access to public tables, Carto enforces secure API access that requires you to authorize your queries. In order to authorize queries, you can use an API Key or a Consumer Key.
|
||||
|
||||
## API Key
|
||||
|
||||
The API Key offers the simplest way to access private data, or perform writes and updates to your public data. Remember that your API Key protects access to your data, so keep it confidential and only share it if you want others to have this access. If necessary, you can reset your API Key from your CartoDB dashboard.
|
||||
The API Key offers the simplest way to access private data, or perform writes and updates to your public data. Remember that your API Key protects access to your data, so keep it confidential and only share it if you want others to have this access. If necessary, you can reset your API Key from your Carto dashboard.
|
||||
|
||||
**Tip:** For details about how to access, or reset, your API Key, see [Your Account](http://docs.cartodb.com/cartodb-editor/your-account/#api-key) details.
|
||||
**Tip:** For details about how to access, or reset, your API Key, see [Your Account](http://docs.carto.com/carto-editor/your-account/#api-key) details.
|
||||
|
||||
To use your API Key, pass it as a parameter in an URL call to the CartoDB API. For example, to perform an insert into your table, you would use the following URL structure.
|
||||
To use your API Key, pass it as a parameter in an URL call to the Carto API. For example, to perform an insert into your table, you would use the following URL structure.
|
||||
|
||||
#### Example
|
||||
|
||||
```bash
|
||||
https://{username}.cartodb.com/api/v2/sql?q={SQL statement}&api_key={api_key}
|
||||
https://{username}.carto.com/api/v2/sql?q={SQL statement}&api_key={api_key}
|
||||
```
|
||||
|
||||
@ -9,7 +9,7 @@ The first is to use the format=GeoJSON method described above. Others can be han
|
||||
#### Call
|
||||
|
||||
```bash
|
||||
https://{username}.cartodb.com/api/v2/sql?q=SELECT cartodb_id,ST_AsGeoJSON(the_geom) as the_geom FROM {table_name} LIMIT 1
|
||||
https://{username}.carto.com/api/v2/sql?q=SELECT carto_id,ST_AsGeoJSON(the_geom) as the_geom FROM {table_name} LIMIT 1
|
||||
```
|
||||
|
||||
#### Result
|
||||
@ -20,7 +20,7 @@ https://{username}.cartodb.com/api/v2/sql?q=SELECT cartodb_id,ST_AsGeoJSON(the_g
|
||||
total_rows: 1,
|
||||
rows: [
|
||||
{
|
||||
cartodb_id: 1,
|
||||
carto_id: 1,
|
||||
the_geom: "{"type":"Point","coordinates":[-97.3349,35.4979]}"
|
||||
}
|
||||
]
|
||||
@ -32,7 +32,7 @@ https://{username}.cartodb.com/api/v2/sql?q=SELECT cartodb_id,ST_AsGeoJSON(the_g
|
||||
#### Call
|
||||
|
||||
```bash
|
||||
https://{username}.cartodb.com/api/v2/sql?q=SELECT cartodb_id,ST_AsText(the_geom) FROM {table_name} LIMIT 1
|
||||
https://{username}.carto.com/api/v2/sql?q=SELECT carto_id,ST_AsText(the_geom) FROM {table_name} LIMIT 1
|
||||
```
|
||||
|
||||
#### Result
|
||||
@ -43,7 +43,7 @@ https://{username}.cartodb.com/api/v2/sql?q=SELECT cartodb_id,ST_AsText(the_geom
|
||||
total_rows: 1,
|
||||
rows: [
|
||||
{
|
||||
cartodb_id: 1,
|
||||
carto_id: 1,
|
||||
the_geom: "POINT(-74.0004162 40.6920918)",
|
||||
}
|
||||
]
|
||||
@ -57,7 +57,7 @@ All data returned from *the_geom* column is in WGS 84 (EPSG:4326). You can chang
|
||||
### ST_Transform
|
||||
|
||||
```bash
|
||||
https://{username}.cartodb.com/api/v2/sql?q=SELECT ST_Transform(the_geom,4147) FROM {table_name} LIMIT 1
|
||||
https://{username}.carto.com/api/v2/sql?q=SELECT ST_Transform(the_geom,4147) FROM {table_name} LIMIT 1
|
||||
```
|
||||
|
||||
CartoDB also stores a second geometry column, *the_geom_webmercator*. We use this internally to build your map tiles as fast as we can. In the user-interface it is hidden, but it is visible and available for use. In this column, we store a reprojected version of all your geometries using Web Mercator (EPSG:3857).
|
||||
Carto also stores a second geometry column, *the_geom_webmercator*. We use this internally to build your map tiles as fast as we can. In the user-interface it is hidden, but it is visible and available for use. In this column, we store a reprojected version of all your geometries using Web Mercator (EPSG:3857).
|
||||
|
||||
@ -3,25 +3,25 @@
|
||||
To make things easier for developers, we provide client libraries for different programming languages and caching functionalities.
|
||||
|
||||
- **R**
|
||||
To help more researchers use CartoDB to drive their geospatial data, we have released the R client library. [Fork it on GitHub!](https://github.com/Vizzuality/cartodb-r)
|
||||
To help more researchers use Carto to drive their geospatial data, we have released the R client library. [Fork it on GitHub!](https://github.com/Vizzuality/cartodb-r)
|
||||
|
||||
- **NODE.js**
|
||||
This demo app authenticates with your CartoDB and shows how to perform read and write queries using the SQL API. [Fork it on GitHub!](https://github.com/Vizzuality/cartodb-nodejs)
|
||||
This demo app authenticates with your Carto and shows how to perform read and write queries using the SQL API. [Fork it on GitHub!](https://github.com/Vizzuality/cartodb-nodejs)
|
||||
|
||||
- **PHP**
|
||||
The PHP library provides a wrapper around the SQL API to get PHP objects straight from SQL calls to CartoDB. [Fork it on GitHub!](https://github.com/Vizzuality/cartodbclient-php)
|
||||
The PHP library provides a wrapper around the SQL API to get PHP objects straight from SQL calls to Carto. [Fork it on GitHub!](https://github.com/Vizzuality/cartodbclient-php)
|
||||
|
||||
- **PYTHON**
|
||||
Provides API Key access to SQL API. [Fork it on GitHub!](https://github.com/vizzuality/cartodb-python)
|
||||
|
||||
- **JAVA**
|
||||
Very basic example of how to access CartoDB SQL API. [Fork it on GitHub!](https://github.com/cartodb/cartodb-java-client)
|
||||
Very basic example of how to access Carto SQL API. [Fork it on GitHub!](https://github.com/cartodb/cartodb-java-client)
|
||||
|
||||
- **NET**
|
||||
.NET library for authenticating with CartoDB using an API Key, based on work started by [The Data Republic](http://www.thedatarepublic.com/). [Fork it on GitHub!](https://github.com/thedatarepublic/CartoDBClientDotNET)
|
||||
.NET library for authenticating with Carto using an API Key, based on work started by [The Data Republic](http://www.thedatarepublic.com/). [Fork it on GitHub!](https://github.com/thedatarepublic/CartoDBClientDotNET)
|
||||
|
||||
- **Clojure**
|
||||
Clojure library for authenticating with CartoDB, maintained by [REDD Metrics](http://www.reddmetrics.com/). [Fork it on GitHub!](https://github.com/reddmetrics/cartodb-clj)
|
||||
Clojure library for authenticating with Carto, maintained by [REDD Metrics](http://www.reddmetrics.com/). [Fork it on GitHub!](https://github.com/reddmetrics/cartodb-clj)
|
||||
|
||||
- **iOS**
|
||||
Objective-C library for interacting with CartoDB in native iOS applications. [Fork it on GitHub!](https://github.com/jmnavarro/cartodb-objectivec-client)
|
||||
Objective-C library for interacting with Carto in native iOS applications. [Fork it on GitHub!](https://github.com/jmnavarro/cartodb-objectivec-client)
|
||||
|
||||
@ -1,18 +1,18 @@
|
||||
# Making Calls to the SQL API
|
||||
|
||||
CartoDB is based on the rock solid PostgreSQL database. All of your tables reside a single database, which means you can perform complex queries joining tables, or carrying out geospatial operations. The best place to learn about PostgreSQL's SQL language is the [official documentation](http://www.postgresql.org/docs/9.1/static/).
|
||||
Carto is based on the rock solid PostgreSQL database. All of your tables reside a single database, which means you can perform complex queries joining tables, or carrying out geospatial operations. The best place to learn about PostgreSQL's SQL language is the [official documentation](http://www.postgresql.org/docs/9.1/static/).
|
||||
|
||||
CartoDB is also based on PostGIS, so take a look at the [official PostGIS reference](http://postgis.refractions.net/docs/) to know what functionality we support in terms of geospatial operations. All of our tables include a column called *the_geom,* which is a geometry field that indexes geometries in the EPSG:4326 (WGS 1984) coordinate system. All tables also have an automatically generated and updated column called *the_geom_webmercator*. We use the column internally to quickly create tiles for maps.
|
||||
Carto is also based on PostGIS, so take a look at the [official PostGIS reference](http://postgis.refractions.net/docs/) to know what functionality we support in terms of geospatial operations. All of our tables include a column called *the_geom,* which is a geometry field that indexes geometries in the EPSG:4326 (WGS 1984) coordinate system. All tables also have an automatically generated and updated column called *the_geom_webmercator*. We use the column internally to quickly create tiles for maps.
|
||||
|
||||
|
||||
## URL endpoints
|
||||
|
||||
All SQL API requests to your CartoDB account should follow this general pattern:
|
||||
All SQL API requests to your Carto account should follow this general pattern:
|
||||
|
||||
#### SQL query example
|
||||
|
||||
```bash
|
||||
https://{username}.cartodb.com/api/v2/sql?q={SQL statement}
|
||||
https://{username}.carto.com/api/v2/sql?q={SQL statement}
|
||||
```
|
||||
|
||||
If you encounter errors, double-check that you are using the correct account name, and that your SQL statement is valid. A simple example of this pattern is conducting a count of all the records in your table:
|
||||
@ -20,7 +20,7 @@ If you encounter errors, double-check that you are using the correct account nam
|
||||
#### Count example
|
||||
|
||||
```bash
|
||||
https://{username}.cartodb.com/api/v2/sql?q=SELECT count(*) FROM {table_name}
|
||||
https://{username}.carto.com/api/v2/sql?q=SELECT count(*) FROM {table_name}
|
||||
```
|
||||
|
||||
#### Result
|
||||
@ -37,38 +37,38 @@ https://{username}.cartodb.com/api/v2/sql?q=SELECT count(*) FROM {table_name}
|
||||
}
|
||||
```
|
||||
|
||||
Finally, remember that in order to use the SQL API, either your table must be public, or you must be [authenticated](http://docs.cartodb.com/cartodb-platform/sql-api/authentication/#authentication) using API Keys.
|
||||
Finally, remember that in order to use the SQL API, either your table must be public, or you must be [authenticated](http://docs.carto.com/carto-engine/sql-api/authentication/#authentication) using API Keys.
|
||||
|
||||
|
||||
## POST and GET
|
||||
|
||||
The CartoDB SQL API is setup to handle both GET and POST requests. You can test the GET method directly in your browser. Below is an example of a jQuery SQL API request to CartoDB:
|
||||
The Carto SQL API is setup to handle both GET and POST requests. You can test the GET method directly in your browser. Below is an example of a jQuery SQL API request to Carto:
|
||||
|
||||
### jQuery
|
||||
|
||||
#### Call
|
||||
|
||||
```javascript
|
||||
$.getJSON('https://{username}.cartodb.com/api/v2/sql/?q='+sql_statement, function(data) {
|
||||
$.getJSON('https://{username}.carto.com/api/v2/sql/?q='+sql_statement, function(data) {
|
||||
$.each(data.rows, function(key, val) {
|
||||
// do something!
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
By default, GET requests work from anywhere. In CartoDB, POST requests work from any website as well. We achieve this by hosting a cross-domain policy file at the root of all of our servers. This allows you the greatest level of flexibility when developing your application.
|
||||
By default, GET requests work from anywhere. In Carto, POST requests work from any website as well. We achieve this by hosting a cross-domain policy file at the root of all of our servers. This allows you the greatest level of flexibility when developing your application.
|
||||
|
||||
|
||||
## Response formats
|
||||
|
||||
The standard response from the CartoDB SQL API is JSON. If you are building a web-application, the lightweight JSON format allows you to quickly integrate data from the SQL API.
|
||||
The standard response from the Carto SQL API is JSON. If you are building a web-application, the lightweight JSON format allows you to quickly integrate data from the SQL API.
|
||||
|
||||
### JSON
|
||||
|
||||
#### Call
|
||||
|
||||
```bash
|
||||
https://{username}.cartodb.com/api/v2/sql?q=SELECT * FROM {table_name} LIMIT 1
|
||||
https://{username}.carto.com/api/v2/sql?q=SELECT * FROM {table_name} LIMIT 1
|
||||
```
|
||||
|
||||
#### Result
|
||||
@ -83,7 +83,7 @@ https://{username}.cartodb.com/api/v2/sql?q=SELECT * FROM {table_name} LIMIT 1
|
||||
month: 10,
|
||||
day: "11",
|
||||
the_geom: "0101000020E610...",
|
||||
cartodb_id: 1,
|
||||
carto_id: 1,
|
||||
the_geom_webmercator: "0101000020110F000..."
|
||||
}
|
||||
]
|
||||
@ -97,7 +97,7 @@ Alternatively, you can use the [GeoJSON specification](http://www.geojson.org/ge
|
||||
#### Call
|
||||
|
||||
```bash
|
||||
https://{username}.cartodb.com/api/v2/sql?format=GeoJSON&q=SELECT * FROM {table_name} LIMIT 1
|
||||
https://{username}.carto.com/api/v2/sql?format=GeoJSON&q=SELECT * FROM {table_name} LIMIT 1
|
||||
```
|
||||
|
||||
#### Result
|
||||
@ -112,7 +112,7 @@ https://{username}.cartodb.com/api/v2/sql?format=GeoJSON&q=SELECT * FROM {table_
|
||||
year: " 2011",
|
||||
month: 10,
|
||||
day: "11",
|
||||
cartodb_id: 1
|
||||
carto_id: 1
|
||||
},
|
||||
geometry: {
|
||||
type: "Point",
|
||||
@ -136,7 +136,7 @@ To customize the output filename, add the `filename` parameter to your URL:
|
||||
#### Call
|
||||
|
||||
```bash
|
||||
https://{username}.cartodb.com/api/v2/sql?filename={custom_filename}&q=SELECT * FROM {table_name} LIMIT 1
|
||||
https://{username}.carto.com/api/v2/sql?filename={custom_filename}&q=SELECT * FROM {table_name} LIMIT 1
|
||||
```
|
||||
|
||||
|
||||
@ -147,13 +147,13 @@ Currently, there is no public method to access your table schemas. The simplest
|
||||
#### Call
|
||||
|
||||
```bash
|
||||
https://{username}.cartodb.com/api/v2/sql?q=SELECT * FROM {table_name} LIMIT 1
|
||||
https://{username}.carto.com/api/v2/sql?q=SELECT * FROM {table_name} LIMIT 1
|
||||
```
|
||||
|
||||
|
||||
## Response errors
|
||||
|
||||
To help you debug your SQL queries, the CartoDB SQL API returns the full error provided by PostgreSQL, as part of the JSON response. Error responses appear in the following format,
|
||||
To help you debug your SQL queries, the Carto SQL API returns the full error provided by PostgreSQL, as part of the JSON response. Error responses appear in the following format,
|
||||
|
||||
#### Result
|
||||
|
||||
@ -165,9 +165,9 @@ To help you debug your SQL queries, the CartoDB SQL API returns the full error p
|
||||
}
|
||||
```
|
||||
|
||||
You can use these errors to help understand your SQL. If you encounter errors executing SQL, either through the CartoDB Editor, or through the SQL API, it is suggested to Google search the error for independent troubleshooting.
|
||||
You can use these errors to help understand your SQL. If you encounter errors executing SQL, either through the Carto Editor, or through the SQL API, it is suggested to Google search the error for independent troubleshooting.
|
||||
|
||||
## Write data to your CartoDB account
|
||||
## Write data to your Carto account
|
||||
|
||||
Performing inserts or updates on your data is simple using your [API Key](#authentication). All you need to do is supply a correct SQL [INSERT](http://www.postgresql.org/docs/9.1/static/sql-insert.html) or [UPDATE](http://www.postgresql.org/docs/9.1/static/sql-update.html) statement for your table along with the api_key parameter for your account. Be sure to keep these requests private, as anyone with your API Key will be able to modify your tables. A correct SQL insert statement means that all the columns you want to insert into already exist in your table, and all the values for those columns are the right type (quoted string, unquoted string for geoms and dates, or numbers).
|
||||
|
||||
@ -176,15 +176,15 @@ Performing inserts or updates on your data is simple using your [API Key](#authe
|
||||
#### Call
|
||||
|
||||
```bash
|
||||
https://{username}.cartodb.com/api/v2/sql?q=INSERT INTO test_table (column_name, column_name_2, the_geom) VALUES ('this is a string', 11, ST_SetSRID(ST_Point(-110, 43),4326))&api_key={api_key}
|
||||
https://{username}.carto.com/api/v2/sql?q=INSERT INTO test_table (column_name, column_name_2, the_geom) VALUES ('this is a string', 11, ST_SetSRID(ST_Point(-110, 43),4326))&api_key={api_key}
|
||||
```
|
||||
|
||||
Updates are just as simple. Here is an example of updating a row based on the value of the cartodb_id column.
|
||||
Updates are just as simple. Here is an example of updating a row based on the value of the carto_id column.
|
||||
|
||||
### Update
|
||||
|
||||
#### Call
|
||||
|
||||
```bash
|
||||
https://{username}.cartodb.com/api/v2/sql?q=UPDATE test_table SET column_name = 'my new string value' WHERE cartodb_id = 1 &api_key={api_key}
|
||||
https://{username}.carto.com/api/v2/sql?q=UPDATE test_table SET column_name = 'my new string value' WHERE carto_id = 1 &api_key={api_key}
|
||||
```
|
||||
|
||||
@ -4,7 +4,5 @@ There are some tricks to consider when using the SQL API that might make your ap
|
||||
|
||||
* Only request the fields you need. Selecting all columns will return a full version of your geometry in *the_geom*, as well as a reprojected version in *the_geom_webmercator*.
|
||||
* Use PostGIS functions to simplify and filter out unneeded geometries when possible. One very handy function is, [ST_Simplify](http://www.postgis.org/docs/ST_Simplify.html).
|
||||
* Remember to build indexes that will speed up some of your more common queries. For details, see [Creating Indexes](http://docs.cartodb.com/cartodb-editor/managing-your-data/#creating-indexes)
|
||||
* Use *cartodb_id* to retrieve specific rows of your data, this is the unique key column added to every CartoDB table.
|
||||
|
||||
<!-- TODO: Link to http://blog.cartodb.com/post/53301057653/faster-data-updates-with-cartodb -->
|
||||
* Remember to build indexes that will speed up some of your more common queries. For details, see [Creating Indexes](http://docs.carto.com/carto-editor/managing-your-data/#creating-indexes)
|
||||
* Use *carto_id* to retrieve specific rows of your data, this is the unique key column added to every Carto table. For a sample use case, view the [_Faster data updates with Carto_](https://blog.carto.com/faster-data-updates-with-carto/) blogpost.
|
||||
@ -2,13 +2,13 @@
|
||||
|
||||
The SQL Batch API enables you to request queries with long-running CPU processing times. Typically, these kind of requests raise timeout errors when using the SQL API. In order to avoid timeouts, you can use the SQL Batch API to [create](#create-a-job), [read](#read-a-job), [list](#list-jobs), [update](#update-a-job) and [cancel](#cancel-a-job) queries. You can also run [multiple](#multi-query-batch-jobs) SQL queries in one job. The SQL Batch API schedules the incoming jobs and allows you to request the job status for each query.
|
||||
|
||||
_The Batch API is not intended to be used for large query payloads than contain over 4096 characters (4kb). For instance, if you are inserting a large number of rows into your table, you still need to use the [Import API](http://docs.cartodb.com/cartodb-platform/import-api/) or [SQL API](http://docs.cartodb.com/cartodb-platform/sql-api/) for this type of data management. The Batch API is specific to queries and CPU usage._
|
||||
_The Batch API is not intended to be used for large query payloads than contain over 4096 characters (4kb). For instance, if you are inserting a large number of rows into your table, you still need to use the [Import API](http://docs.carto.com/carto-engine/import-api/) or [SQL API](http://docs.carto.com/carto-engine/sql-api/) for this type of data management. The Batch API is specific to queries and CPU usage._
|
||||
|
||||
**Note:** In order to use the SQL Batch API, your table must be public, or you must be [authenticated](http://docs.cartodb.com/cartodb-platform/sql-api/authentication/#authentication) using API keys. For details about how to manipulate private datasets with the SQL Batch API, see [Private Datasets](#private-datasets).
|
||||
**Note:** In order to use the SQL Batch API, your table must be public, or you must be [authenticated](http://docs.carto.com/carto-engine/sql-api/authentication/#authentication) using API keys. For details about how to manipulate private datasets with the SQL Batch API, see [Private Datasets](#private-datasets).
|
||||
|
||||
## SQL Batch API Job Schema
|
||||
|
||||
The SQL Batch API request to your CartoDB account includes the following job schema elements. _Only the `query` element can be modified._ All other elements of the job schema are defined by the SQL Batch API and are read-only.
|
||||
The SQL Batch API request to your Carto account includes the following job schema elements. _Only the `query` element can be modified._ All other elements of the job schema are defined by the SQL Batch API and are read-only.
|
||||
|
||||
Name | Description
|
||||
--- | ---
|
||||
@ -74,8 +74,8 @@ If you are using the Batch API create operation for cURL POST request, use the f
|
||||
|
||||
```bash
|
||||
curl -X POST -H "Content-Type: application/json" -d '{
|
||||
"query": "CREATE TABLE world_airports AS SELECT a.cartodb_id, a.the_geom, a.the_geom_webmercator, a.name airport, b.name country FROM world_borders b JOIN airports a ON ST_Contains(b.the_geom, a.the_geom)"
|
||||
}' "http://{username}.cartodb.com/api/v2/sql/job"
|
||||
"query": "CREATE TABLE world_airports AS SELECT a.carto_id, a.the_geom, a.the_geom_webmercator, a.name airport, b.name country FROM world_borders b JOIN airports a ON ST_Contains(b.the_geom, a.the_geom)"
|
||||
}' "http://{username}.carto.com/api/v2/sql/job"
|
||||
```
|
||||
|
||||
If you are using the Batch API create operation for a Node.js client POST request, use the following code:
|
||||
@ -85,10 +85,10 @@ var request = require("request");
|
||||
|
||||
var options = {
|
||||
method: "POST",
|
||||
url: "http://{username}.cartodb.com/api/v2/sql/job",
|
||||
url: "http://{username}.carto.com/api/v2/sql/job",
|
||||
headers: { "content-type": "application/json" },
|
||||
body: {
|
||||
query: "CREATE TABLE world_airports AS SELECT a.cartodb_id, a.the_geom, a.the_geom_webmercator, a.name airport, b.name country FROM world_borders b JOIN airports a ON ST_Contains(b.the_geom, a.the_geom)"
|
||||
query: "CREATE TABLE world_airports AS SELECT a.carto_id, a.the_geom, a.the_geom_webmercator, a.name airport, b.name country FROM world_borders b JOIN airports a ON ST_Contains(b.the_geom, a.the_geom)"
|
||||
},
|
||||
json: true
|
||||
};
|
||||
@ -128,7 +128,7 @@ BODY: {
|
||||
If you are using the Batch API read operation for cURL GET request, use the following code:
|
||||
|
||||
```bash
|
||||
curl -X GET "http://{username}.cartodb.com/api/v2/sql/job/{job_id}"
|
||||
curl -X GET "http://{username}.carto.com/api/v2/sql/job/{job_id}"
|
||||
```
|
||||
|
||||
If you are using the Batch API read operation for a Node.js client GET request, use the following code:
|
||||
@ -138,7 +138,7 @@ var request = require("request");
|
||||
|
||||
var options = {
|
||||
method: "GET",
|
||||
url: "http://{username}.cartodb.com/api/v2/sql/job/{job_id}"
|
||||
url: "http://{username}.carto.com/api/v2/sql/job/{job_id}"
|
||||
};
|
||||
|
||||
request(options, function (error, response, body) {
|
||||
@ -171,7 +171,7 @@ BODY: [{
|
||||
}, {
|
||||
"job_id": "ba25ed54-75b4-431b-af27-eb6b9e5428ff",
|
||||
"user": "cartofante"
|
||||
"query": "CREATE TABLE world_airports AS SELECT a.cartodb_id, a.the_geom, a.the_geom_webmercator, a.name airport, b.name country FROM world_borders b JOIN airports a ON ST_Contains(b.the_geom, a.the_geom)",
|
||||
"query": "CREATE TABLE world_airports AS SELECT a.carto_id, a.the_geom, a.the_geom_webmercator, a.name airport, b.name country FROM world_borders b JOIN airports a ON ST_Contains(b.the_geom, a.the_geom)",
|
||||
"status": "pending",
|
||||
"created_at": "2015-12-15T07:43:12Z",
|
||||
"updated_at": "2015-12-15T07:43:12Z"
|
||||
@ -183,7 +183,7 @@ BODY: [{
|
||||
If you are using the Batch API list operation for cURL GET request, use the following code:
|
||||
|
||||
```bash
|
||||
curl -X GET "http://{username}.cartodb.com/api/v2/sql/job"
|
||||
curl -X GET "http://{username}.carto.com/api/v2/sql/job"
|
||||
```
|
||||
|
||||
If you are using the Batch API list operation for a Node.js client GET request, use the following code:
|
||||
@ -193,7 +193,7 @@ var request = require("request");
|
||||
|
||||
var options = {
|
||||
method: "GET",
|
||||
url: "http://{username}.cartodb.com/api/v2/sql/job"
|
||||
url: "http://{username}.carto.com/api/v2/sql/job"
|
||||
};
|
||||
|
||||
request(options, function (error, response, body) {
|
||||
@ -243,7 +243,7 @@ If you are using the Batch API update operation for cURL PUT request, use the fo
|
||||
```bash
|
||||
curl -X PUT -H "Content-Type: application/json" -d '{
|
||||
"query": "UPDATE airports SET type = 'military'"
|
||||
}' "http://{username}.cartodb.com/api/v2/sql/job/{job_id}"
|
||||
}' "http://{username}.carto.com/api/v2/sql/job/{job_id}"
|
||||
```
|
||||
|
||||
If you are using the Batch API update operation for a Node.js client PUT request, use the following code:
|
||||
@ -253,7 +253,7 @@ var request = require("request");
|
||||
|
||||
var options = {
|
||||
method: "PUT",
|
||||
url: "http://{username}.cartodb.com/api/v2/sql/job/{job_id}",
|
||||
url: "http://{username}.carto.com/api/v2/sql/job/{job_id}",
|
||||
headers: {
|
||||
"content-type": "application/json"
|
||||
},
|
||||
@ -309,7 +309,7 @@ errors: [
|
||||
If you are using the Batch API cancel operation for cURL DELETE request, use the following code:
|
||||
|
||||
```bash
|
||||
curl -X DELETE "http://{username}.cartodb.com/api/v2/sql/job/{job_id}"
|
||||
curl -X DELETE "http://{username}.carto.com/api/v2/sql/job/{job_id}"
|
||||
```
|
||||
|
||||
If you are using the Batch API cancel operation for a Node.js client DELETE request, use the following code:
|
||||
@ -319,7 +319,7 @@ var request = require("request");
|
||||
|
||||
var options = {
|
||||
method: "DELETE",
|
||||
url: "http://{username}.cartodb.com/api/v2/sql/job/{job_id}",
|
||||
url: "http://{username}.carto.com/api/v2/sql/job/{job_id}",
|
||||
};
|
||||
|
||||
request(options, function (error, response, body) {
|
||||
@ -337,7 +337,7 @@ In some cases, you may need to run multiple SQL queries in one job. The Multi Qu
|
||||
HEADERS: POST /api/v2/sql/job
|
||||
BODY: {
|
||||
query: [
|
||||
"CREATE TABLE world_airports AS SELECT a.cartodb_id, a.the_geom, a.the_geom_webmercator, a.name airport, b.name country FROM world_borders b JOIN airports a ON ST_Contains(b.the_geom, a.the_geom)",
|
||||
"CREATE TABLE world_airports AS SELECT a.carto_id, a.the_geom, a.the_geom_webmercator, a.name airport, b.name country FROM world_borders b JOIN airports a ON ST_Contains(b.the_geom, a.the_geom)",
|
||||
"DROP TABLE airports",
|
||||
"ALTER TABLE world_airports RENAME TO airport"
|
||||
]
|
||||
@ -352,7 +352,7 @@ BODY: {
|
||||
"job_id": "de305d54-75b4-431b-adb2-eb6b9e546014",
|
||||
"user": "cartofante"
|
||||
"query": [{
|
||||
"query": "CREATE TABLE world_airports AS SELECT a.cartodb_id, a.the_geom, a.the_geom_webmercator, a.name airport, b.name country FROM world_borders b JOIN airports a ON ST_Contains(b.the_geom, a.the_geom)",
|
||||
"query": "CREATE TABLE world_airports AS SELECT a.carto_id, a.the_geom, a.the_geom_webmercator, a.name airport, b.name country FROM world_borders b JOIN airports a ON ST_Contains(b.the_geom, a.the_geom)",
|
||||
"status": "pending"
|
||||
}, {
|
||||
"query": "DROP TABLE airports",
|
||||
@ -382,11 +382,11 @@ If you are using the Batch API Multi Query operation for cURL POST request, use
|
||||
```bash
|
||||
curl -X POST -H "Content-Type: application/json" -d '{
|
||||
"query": [
|
||||
"CREATE TABLE world_airports AS SELECT a.cartodb_id, a.the_geom, a.the_geom_webmercator, a.name airport, b.name country FROM world_borders b JOIN airports a ON ST_Contains(b.the_geom, a.the_geom)",
|
||||
"CREATE TABLE world_airports AS SELECT a.carto_id, a.the_geom, a.the_geom_webmercator, a.name airport, b.name country FROM world_borders b JOIN airports a ON ST_Contains(b.the_geom, a.the_geom)",
|
||||
"DROP TABLE airports",
|
||||
"ALTER TABLE world_airports RENAME TO airport"
|
||||
]
|
||||
}' "http://{username}.cartodb.com/api/v2/sql/job"
|
||||
}' "http://{username}.carto.com/api/v2/sql/job"
|
||||
```
|
||||
|
||||
If you are using the Batch API Multi Query operation for a Node.js client POST request, use the following code:
|
||||
@ -396,11 +396,11 @@ var request = require("request");
|
||||
|
||||
var options = {
|
||||
method: "POST",
|
||||
url: "http://{username}.cartodb.com/api/v2/sql/job",
|
||||
url: "http://{username}.carto.com/api/v2/sql/job",
|
||||
headers: { "content-type": "application/json" },
|
||||
body: {
|
||||
"query": [
|
||||
"CREATE TABLE world_airports AS SELECT a.cartodb_id, a.the_geom, a.the_geom_webmercator, a.name airport, b.name country FROM world_borders b JOIN airports a ON ST_Contains(b.the_geom, a.the_geom)",
|
||||
"CREATE TABLE world_airports AS SELECT a.carto_id, a.the_geom, a.the_geom_webmercator, a.name airport, b.name country FROM world_borders b JOIN airports a ON ST_Contains(b.the_geom, a.the_geom)",
|
||||
"DROP TABLE airports",
|
||||
"ALTER TABLE world_airports RENAME TO airport"
|
||||
]
|
||||
@ -422,12 +422,12 @@ If you are using the Batch API Multi Query operation for cURL PUT request, use t
|
||||
```bash
|
||||
curl -X PUT -H "Content-Type: application/json" -d '{
|
||||
"query": [
|
||||
"CREATE TABLE world_airports AS SELECT a.cartodb_id, a.the_geom, a.the_geom_webmercator, a.name airport, b.name country FROM world_borders b JOIN airports a ON ST_Contains(b.the_geom, a.the_geom)",
|
||||
"CREATE TABLE world_airports AS SELECT a.carto_id, a.the_geom, a.the_geom_webmercator, a.name airport, b.name country FROM world_borders b JOIN airports a ON ST_Contains(b.the_geom, a.the_geom)",
|
||||
"DROP TABLE airports",
|
||||
"ALTER TABLE world_airports RENAME TO airport",
|
||||
"UPDATE airports SET airport = upper(airport)"
|
||||
]
|
||||
}' "http://{username}.cartodb.com/api/v2/sql/job/{job_id}"
|
||||
}' "http://{username}.carto.com/api/v2/sql/job/{job_id}"
|
||||
```
|
||||
|
||||
If you are using the Batch API Multi Query operation for a Node.js client PUT request, use the following code:
|
||||
@ -437,11 +437,11 @@ var request = require("request");
|
||||
|
||||
var options = {
|
||||
method: "PUT",
|
||||
url: "http://{username}.cartodb.com/api/v2/sql/job/{job_id}",
|
||||
url: "http://{username}.carto.com/api/v2/sql/job/{job_id}",
|
||||
headers: { "content-type": "application/json" },
|
||||
body: {
|
||||
query: [
|
||||
"CREATE TABLE world_airports AS SELECT a.cartodb_id, a.the_geom, a.the_geom_webmercator, a.name airport, b.name country FROM world_borders b JOIN airports a ON ST_Contains(b.the_geom, a.the_geom)",
|
||||
"CREATE TABLE world_airports AS SELECT a.carto_id, a.the_geom, a.the_geom_webmercator, a.name airport, b.name country FROM world_borders b JOIN airports a ON ST_Contains(b.the_geom, a.the_geom)",
|
||||
"DROP TABLE airports",
|
||||
"ALTER TABLE world_airports RENAME TO airport",
|
||||
"UPDATE airports SET airport = upper(airport)"
|
||||
@ -465,13 +465,13 @@ In some scenarios, you may need to fetch the output of a job. If that is the cas
|
||||
|
||||
2. [Create a job](#create-a-job), as described previously
|
||||
|
||||
3. Once the job is done, fetch the results through the [CartoDB SQL API](http://docs.cartodb.com/cartodb-platform/sql-api/), `SELECT * FROM job_result`
|
||||
3. Once the job is done, fetch the results through the [Carto SQL API](http://docs.carto.com/carto-engine/sql-api/), `SELECT * FROM job_result`
|
||||
|
||||
**Note:** If you need to create a map or analysis with the new table, use the [CDB_CartodbfyTable function](https://github.com/CartoDB/cartodb-postgresql/blob/master/doc/cartodbfy-requirements.rst).
|
||||
**Note:** If you need to create a map or analysis with the new table, use the [CDB_CartofyTable function](https://github.com/CartoDB/cartodb-postgresql/blob/master/doc/cartodbfy-requirements.rst).
|
||||
|
||||
## Private Datasets
|
||||
|
||||
For access to all private tables, and for write access to public tables, an API Key is required to [authenticate](http://docs.cartodb.com/cartodb-platform/sql-api/authentication/#authentication) your queries with the Batch API. The following error message appears if you are using private tables and are not authenticated:
|
||||
For access to all private tables, and for write access to public tables, an API Key is required to [authenticate](http://docs.carto.com/carto-engine/sql-api/authentication/#authentication) your queries with the Batch API. The following error message appears if you are using private tables and are not authenticated:
|
||||
|
||||
```bash
|
||||
{
|
||||
@ -488,7 +488,7 @@ Using cURL tool:
|
||||
```bash
|
||||
curl -X POST -H "Content-Type: application/json" -d '{
|
||||
"query": "{query}"
|
||||
}' "http://{username}.cartodb.com/api/v2/sql/job?api_key={api_key}"
|
||||
}' "http://{username}.carto.com/api/v2/sql/job?api_key={api_key}"
|
||||
```
|
||||
|
||||
Using Node.js request client:
|
||||
@ -498,7 +498,7 @@ var request = require("request");
|
||||
|
||||
var options = {
|
||||
method: "POST",
|
||||
url: "http://{username}.cartodb.com/api/v2/sql/job",
|
||||
url: "http://{username}.carto.com/api/v2/sql/job",
|
||||
qs: {
|
||||
"api_key": "{api_key}"
|
||||
},
|
||||
@ -522,7 +522,7 @@ request(options, function (error, response, body) {
|
||||
|
||||
For best practices, ensure that you are following these recommended usage notes when using the SQL Batch API:
|
||||
|
||||
- The Batch API is not intended for large query payloads (e.g: inserting thousands of rows), use the [Import API](http://docs.cartodb.com/cartodb-platform/import-api/) for this type of data management
|
||||
- The Batch API is not intended for large query payloads (e.g: inserting thousands of rows), use the [Import API](http://docs.carto.com/carto-engine/import-api/) for this type of data management
|
||||
|
||||
- There is a limit of 4kb per job. The following error message appears if your job exceeds this size:
|
||||
|
||||
|
||||
@ -1,39 +1,39 @@
|
||||
# Other Tips and Questions
|
||||
|
||||
## What does CartoDB do to prevent SQL injection?
|
||||
## What does Carto do to prevent SQL injection?
|
||||
|
||||
CartoDB uses the database access mechanism for security. Every writable connection is verified by an API Key. If you have the correct API Key, you can write-access to the database. If you do not have the correct API Key, your client is "logged in" as a low privilege user, and you have read-only access to the database (if the database allows you to read).
|
||||
Carto uses the database access mechanism for security. Every writable connection is verified by an API Key. If you have the correct API Key, you can write-access to the database. If you do not have the correct API Key, your client is "logged in" as a low privilege user, and you have read-only access to the database (if the database allows you to read).
|
||||
|
||||
SQL injection works by tricking a database user, so that running a query retrieves database wide results, even though the database is protected.
|
||||
|
||||
Because CartoDB enforces roles and access at the database level, the idea of a "SQL injection attack" is not possible with CartoDB. Injection is possible, but clients will still run into our security wall at the database level. The SQL API already lets you _attempt_ to run any query you want. The database will reject your SQL API request if it finds your user/role does not have the requisite permissions. In other words, you can ask any question of the database you like; the CartoDB database does not guarantee it will be answered.
|
||||
Because Carto enforces roles and access at the database level, the idea of a "SQL injection attack" is not possible with Carto. Injection is possible, but clients will still run into our security wall at the database level. The SQL API already lets you _attempt_ to run any query you want. The database will reject your SQL API request if it finds your user/role does not have the requisite permissions. In other words, you can ask any question of the database you like; the Carto database does not guarantee it will be answered.
|
||||
|
||||
If a user's API Key found its way out into the wild, that could be a problem, but it is not something CartoDB can prevent. _This is why it is very important for all CartoDB users to secure their API Keys_. In the event a user's API Key is compromised, the user (or the CartoDB Enterprise administrator), can regenerate the API Key in their account settings.
|
||||
If a user's API Key found its way out into the wild, that could be a problem, but it is not something Carto can prevent. _This is why it is very important for all Carto users to secure their API Keys_. In the event a user's API Key is compromised, the user (or the Carto Enterprise administrator), can regenerate the API Key in their account settings.
|
||||
|
||||
**Note:** While the SQL API is SQL injection secure, if you build additional layers to allow another person to run queries (i.e., building a proxy so that others can indirectly perform authenticated queries through the SQL API), the security of those newly added layers are the responsibility of the creator.
|
||||
|
||||
## What levels of database access can roles/users have?
|
||||
|
||||
There are three levels of access with CartoDB:
|
||||
There are three levels of access with Carto:
|
||||
|
||||
1. __API Key level:__ Do whatever you want in your account on the tables you own (or have been shared with you in Enterprise/multi-user accounts).
|
||||
2. __"publicuser" level:__ Do whatever has been granted to you. The publicuser level is normally read-only, but you could GRANT INSERT/UPDATE/DELETE permissions to publicuser if needed for some reason - for API Key-less write operations. Use with caution.
|
||||
3. __postgres superadmin level:__ This third access level, the actual PostgreSQL system user, is only accessible from a direct database connection via the command line, which is only available currently via [CartoDB On-Premises](https://cartodb.com/on-premises/).
|
||||
3. __postgres superadmin level:__ This third access level, the actual PostgreSQL system user, is only accessible from a direct database connection via the command line, which is only available currently via [Carto On-Premises](https://carto.com/on-premises/).
|
||||
|
||||
## If a user has write access and makes a `DROP TABLE` query, is that data gone?
|
||||
|
||||
Yes. Grant write access with caution and keep backups of your data elsewhere / as duplicate CartoDB tables.
|
||||
Yes. Grant write access with caution and keep backups of your data elsewhere / as duplicate Carto tables.
|
||||
|
||||
## Is there an in between where a user can write but not `DROP` or `DELETE`?
|
||||
|
||||
Yes. Create the table, and GRANT INSERT/UPDATE to the user.
|
||||
|
||||
## Is there an actual PostgreSQL account for each CartoDB login/username?
|
||||
## Is there an actual PostgreSQL account for each Carto login/username?
|
||||
|
||||
Yes, there is. Unfortunately, the names are different - though there is a way to determine the name of the PostgreSQL user account. Every CartoDB user gets their own PostgreSQL database. But there is a system database too, with the name mappings in `username` and `database_name` columns. `database_name` is the name of the database that user belongs to. It will be `cartodb_user_ID`. `id` holds long hashkey. The `database_name` is derived from this ID hash too, but in case of an Enterprise/multi-user account it will come from the user ID of the owner of the organization - and `database_name` will hold the same value for every user in an Enterprise/multi-user account.
|
||||
Yes, there is. Unfortunately, the names are different - though there is a way to determine the name of the PostgreSQL user account. Every Carto user gets their own PostgreSQL database. But there is a system database too, with the name mappings in `username` and `database_name` columns. `database_name` is the name of the database that user belongs to. It will be `carto_user_ID`. `id` holds long hashkey. The `database_name` is derived from this ID hash too, but in case of an Enterprise/multi-user account it will come from the user ID of the owner of the organization - and `database_name` will hold the same value for every user in an Enterprise/multi-user account.
|
||||
|
||||
You can also just do `select user` using the SQL API (without an API Key to get the publicuser name and with an API Key to get the CartoDB user's PostgreSQL user name), to determine the name of the corresponding PostgreSQL user.
|
||||
You can also just do `select user` using the SQL API (without an API Key to get the publicuser name and with an API Key to get the Carto user's PostgreSQL user name), to determine the name of the corresponding PostgreSQL user.
|
||||
|
||||
## Can I configure my CartoDB database permissions exactly the same way I do on my own PostgreSQL instance?
|
||||
## Can I configure my Carto database permissions exactly the same way I do on my own PostgreSQL instance?
|
||||
|
||||
Yes, through using GRANT statements to the SQL API. There are a few caveats to be aware of, including the aforementioned naming differences. Also, you will be limited to permissions a user has with their own tables. Users do not have PostgreSQL superuser privileges. So they cannot be creating languages, or C functions, or anything that requires superuser or CREATEUSER privileges.
|
||||
|
||||
@ -1,3 +1,3 @@
|
||||
# API Version Number
|
||||
|
||||
All CartoDB applications use **Version 2** of our APIs. All other APIs are deprecated and will not be maintained or supported. You can check that you are using **Version 2** of our APIs by looking at your request URLS. They should all begin containing **/v2/** in the URLs as follows, `https://{username}.cartodb.com/api/v2/`
|
||||
All Carto applications use **Version 2** of our APIs. All other APIs are deprecated and will not be maintained or supported. You can check that you are using **Version 2** of our APIs by looking at your request URLS. They should all begin containing **/v2/** in the URLs as follows, `https://{username}.carto.com/api/v2/`
|
||||
|
||||
Loading…
Reference in New Issue
Block a user