94 lines
2.9 KiB
Markdown
94 lines
2.9 KiB
Markdown
# Getting Data with SQL
|
||
|
||
CARTO offers a powerful SQL API for you to query and retreive data from your CARTO tables. CARTO.js offers a simple to use wrapper for sending those requests and using the results.
|
||
|
||
## cartodb.SQL
|
||
|
||
`cartodb.SQL` is the tool you will use to access data you store in your CARTO tables. This is a really powerful technique for returning things like: **items closest to a point**, **items ordered by date**, or **GeoJSON vector geometries**. It’s all powered with SQL and our tutorials will show you how easy it is to begin with SQL.
|
||
|
||
#### Arguments
|
||
|
||
Name | Description
|
||
--- | ---
|
||
format | should be GeoJSON.
|
||
dp | float precision.
|
||
jsonp | if jsonp should be used instead of CORS. This param is enabled if the browser does not support CORS.
|
||
|
||
These arguments will be applied to all the queries performed by this object. If you want to override them for one query see **execute** options.
|
||
|
||
#### Example
|
||
|
||
```javascript
|
||
var sql = new cartodb.SQL({ user: 'cartodb_user' });
|
||
sql.execute("SELECT * FROM table_name WHERE id > {{id}}", { id: 3 })
|
||
.done(function(data) {
|
||
console.log(data.rows);
|
||
})
|
||
.error(function(errors) {
|
||
// errors contains a list of errors
|
||
console.log("errors:" + errors);
|
||
})
|
||
```
|
||
|
||
## sql.execute(_sql [,vars][, options][, callback]_)
|
||
|
||
It executes a sql query.
|
||
|
||
#### Arguments
|
||
|
||
Name |Description
|
||
--- | ---
|
||
sql | a string with the sql query to be executed. You can specify template variables like {{variable}} which will be filled with `vars` object.
|
||
vars | a map with the variables to be interpolated in the sql query.
|
||
options | accepts `format`, `dp` and `jsonp`. This object also overrides the params passed to `$.ajax`.
|
||
|
||
#### Returns
|
||
|
||
A promise object. You can listen for the following events:
|
||
|
||
Events | Description
|
||
--- | ---
|
||
done | triggered when the data arrives.
|
||
error | triggered when something failed.
|
||
|
||
#### Example
|
||
|
||
You can also use done and error methods:
|
||
|
||
```javascript
|
||
sql.execute('SELECT * FROM table_name')
|
||
.done(fn)
|
||
.error(fnError)
|
||
```
|
||
|
||
## sql.getBounds(_sql [,vars][, options][, callback]_)
|
||
|
||
This query gets the bounding box for any dataset or filtered query using the CARTO.js library. The **getBounds** function is useful for guiding users to the right location on a map, or for loading the right data (at the right time), based on user actions.
|
||
|
||
Returns the bounds `[ [sw_lat, sw_lon], [ne_lat, ne_lon ] ]` for the geometry resulting of specified query.
|
||
|
||
#### Arguments
|
||
|
||
Name |Description
|
||
--- | ---
|
||
sql | a string with the sql query to calculate the bounds from.
|
||
|
||
#### Example
|
||
|
||
```javascript
|
||
sql.getBounds('select * from table').done(function(bounds) {
|
||
console.log(bounds);
|
||
});
|
||
```
|
||
|
||
### getBounds and Leaflet
|
||
|
||
You can use the results from `getBounds` to center data on your maps using Leaflet.
|
||
|
||
```javascript
|
||
sql.getBounds('select * from table').done(function(bounds) {
|
||
map.setBounds(bounds);
|
||
// or map.fitBounds(bounds, mapView.getSize());
|
||
});
|
||
```
|