Add new docs folder structure
This commit is contained in:
csubira
135
docs/support/01-quota-information.md
Normal file
135
docs/support/01-quota-information.md
Normal file
@@ -0,0 +1,135 @@
|
||||
## Quota Information
|
||||
|
||||
**Based on your account plan, some of the Data Services API functions are subject to quota limitations and extra fees may apply.** View our [terms and conditions](https://carto.com/terms/), or [contact us](mailto:sales@carto.com) for details about which functions require service credits to your account.
|
||||
|
||||
### Quota Consumption
|
||||
|
||||
Quota consumption is calculated based on the number of request made for each function. Be mindful of the following usage recommendations when using the Data Services API functions:
|
||||
|
||||
* One credit per function call will be consumed. The results are not cached. If the query is applied to a _N_ rows dataset, then _N_ credits are consumed
|
||||
* Avoid running dynamic queries to these functions in your maps. This can result in credit consumption per map view.
|
||||
|
||||
**Note:** Queries to the Data Services API, and any of its functions in your maps, may be forbidden in the future
|
||||
|
||||
* It is advised to store results of these queries into your datasets, and refresh them as needed. This ensure more control of quota credits for your account
|
||||
|
||||
|
||||
### Quota Information Functions
|
||||
|
||||
There are several SQL functions that you can run to obtain quota information about your services.
|
||||
|
||||
### cdb_service_quota_info()
|
||||
|
||||
Returns information about per-service quotas (available and used) for the account.
|
||||
|
||||
##### Returns
|
||||
|
||||
This function returns a set of service quota information records, one per service.
|
||||
|
||||
Name | Type | Description
|
||||
--------------- | --------- | ------------
|
||||
`service` | `text` | Type of service.
|
||||
`monthly_quota` | `numeric` | Quota available to the user (number of calls) per monthly period.
|
||||
`used_quota` | `numeric` | Quota used by the user in the present period.
|
||||
`soft_limit` | `boolean` | Set to `True`, if the user has *soft-limit* quota.
|
||||
`provider` | `text` | Service provider for this type of service.
|
||||
|
||||
Service Types:
|
||||
|
||||
* `'isolines'` [Isoline/Isochrones (isochrone/isodistance lines) service](https://carto.com/docs/carto-engine/dataservices-api/isoline_functions/)
|
||||
* `'hires_geocoder'` [Street level geocoding](https://carto.com/docs/carto-engine/dataservices-api/geocoding-functions#street-level-geocoder)
|
||||
* `'routing'` [Routing functions](https://carto.com/docs/carto-engine/dataservices-api/routing_functions/)
|
||||
* `'observatory'` Data Observatory services ([demographic](https://carto.com/docs/carto-engine/dataservices-api/demographic_functions/) and [segmentation](https://carto.com/docs/carto-engine/dataservices-api/segmentation_functions/) functions)
|
||||
|
||||
**Notes**
|
||||
|
||||
Users who have *soft-quota* activated never run out of quota, but they may incur extra
|
||||
expenses when the regular quota is exceeded.
|
||||
|
||||
A zero value of `monthly_quota` indicates that the service has not been activated for the user.
|
||||
|
||||
##### Example
|
||||
|
||||
```sql
|
||||
SELECT * FROM cdb_service_quota_info();
|
||||
```
|
||||
|
||||
Result:
|
||||
|
||||
```sql
|
||||
service | monthly_quota | used_quota | soft_limit | provider
|
||||
----------------+---------------+------------+------------+------------------
|
||||
isolines | 100 | 0 | f | mapbox
|
||||
hires_geocoder | 100 | 0 | f | mapbox
|
||||
routing | 50 | 0 | f | mapbox
|
||||
observatory | 0 | 0 | f | data observatory
|
||||
(4 rows)
|
||||
|
||||
```
|
||||
|
||||
In this case, notice that the user has no access to the observatory services. All quotas are *hard-limited* (no soft limits), and no quota has been used in the present period.
|
||||
|
||||
### cdb_enough_quota(service text ,input_size numeric)
|
||||
|
||||
This function is useful to check if enough quota is available for completing a job.
|
||||
|
||||
This is specifically relevant if a number of service calls are to be performed inside a transaction. If any of the calls fails (due to exceeded quota), the transaction will be rolled back; resulting in partial quota consumption, but no saved results from the services consumed.
|
||||
|
||||
**Tip:** If you are requesting repeating quota-consuming functions (e.g. to geocode a whole table), it is extremely important to check if enough quota is available to complete the job _before_ applying this function.
|
||||
|
||||
Note that some services consume more than one credit per row/call. For example, isolines (with more than one range/track) consume (N rows x M ranges) credits; indicating that the input size should be N x M.
|
||||
|
||||
##### Arguments
|
||||
|
||||
Name | Type | Description
|
||||
------------ | --------- | -----------
|
||||
`service` | `text` | Service to check; see the list of valid services above.
|
||||
`input_size` | `numeric` | Number of service calls required, i.e. size of the input to be processed.
|
||||
|
||||
##### Returns
|
||||
|
||||
The result is a *boolean* value. A *true* value (`'t'`) indicates that the available quota
|
||||
for the service is enough for the input size requested. A *false* value (`'f'`) indicates
|
||||
insufficient quota.
|
||||
|
||||
##### Example
|
||||
|
||||
Suppose you want to geocode a whole table. In order to check that you have enough quota, and avoid a "quota exhausted" exception, first find out how many records you need to geocode:
|
||||
|
||||
```sql
|
||||
SELECT COUNT(*) FROM {tablename} WHERE {street_name_column} IS NOT NULL;
|
||||
```
|
||||
|
||||
Result: A sample result of 10000 records:
|
||||
|
||||
```sql
|
||||
count
|
||||
-------
|
||||
10000
|
||||
(1 row)
|
||||
```
|
||||
|
||||
The result shows how much quota is needed to complete this job. In this case,
|
||||
each call to `cdb_geocode_street_point` consumes one quota credit. This indicates that we need one credit per row to geocode the whole table.
|
||||
|
||||
```sql
|
||||
SELECT cdb_enough_quota('hires_geocoder', {number_of_records});
|
||||
```
|
||||
|
||||
The result is similar to the following:
|
||||
|
||||
```sql
|
||||
cdb_enough_quota
|
||||
------------------
|
||||
t
|
||||
```
|
||||
|
||||
If the result of this query is *true* (`'t'`), you can safely proceed. If a *false* value (`'f'`) is returned, you should avoid processing any more requests that consume quota. Apply the `cdb_service_quota_info` function to get more information about your services.
|
||||
|
||||
**Note:** Remember to apply any filtering conditions that you used to count the records (in this case, `{street_name_column} IS NOT NULL`):
|
||||
|
||||
|
||||
```sql
|
||||
UPDATE {tablename} SET the_geom = cdb_geocode_street_point({street_name_column})
|
||||
WHERE {street_name_column} IS NOT NULL;
|
||||
```
|
||||
197
docs/support/02-rate-limits.md
Normal file
197
docs/support/02-rate-limits.md
Normal file
@@ -0,0 +1,197 @@
|
||||
## Rate limits
|
||||
|
||||
Services can be rate-limited. (currently only gecoding is limited)
|
||||
|
||||
The rate limits configuration can be established at server, organization or user levels, the latter having precedence over the earlier.
|
||||
|
||||
The default configuration (a null or empty configuration) doesn't impose any limits.
|
||||
|
||||
The configuration consist of a JSON object with two attributes:
|
||||
|
||||
* `period`: the rate-limiting period, in seconds.
|
||||
* `limit`: the maximum number of request in the established period.
|
||||
|
||||
If a service request exceeds the configured rate limits
|
||||
(i.e. if more than `limit` calls are performe in a fixed interval of
|
||||
duration `period` seconds) the call will fail with an "Rate limit exceeded" error.
|
||||
|
||||
### Server-side interface
|
||||
|
||||
There's a server-side SQL interface to query or change the configuration.
|
||||
|
||||
#### cdb_dataservices_server.cdb_service_get_rate_limit(username, orgname, service)
|
||||
|
||||
This function returns the rate limit configuration for a given user and service.
|
||||
|
||||
##### Returns
|
||||
|
||||
The result is a JSON object with the configuration (`period` and `limit` attributes as explained above).
|
||||
|
||||
#### cdb_dataservices_server.cdb_service_set_user_rate_limit(username, orgname, service, rate_limit)
|
||||
|
||||
This function sets the rate limit configuration for the user. This overrides any other configuration.
|
||||
|
||||
The configuration is provided as a JSON literal. To remove the user-level configuration `NULL` should be passed as the `rate_limit`.
|
||||
|
||||
##### Returns
|
||||
|
||||
This functions doesn't return any value.
|
||||
|
||||
#### cdb_dataservices_server.cdb_service_set_org_rate_limit(username, orgname, service, rate_limit)
|
||||
|
||||
This function sets the rate limit configuration for the organization.
|
||||
This overrides server level configuration and is overriden by user configuration if present.
|
||||
|
||||
The configuration is provided as a JSON literal. To remove the organization-level configuration `NULL` should be passed as the `rate_limit`.
|
||||
|
||||
##### Returns
|
||||
|
||||
This functions doesn't return any value.
|
||||
|
||||
#### cdb_dataservices_server.cdb_service_set_server_rate_limit(username, orgname, service, rate_limit)
|
||||
|
||||
This function sets the default rate limit configuration for all users accesing the dataservices server. This is overriden by organization of user configuration.
|
||||
|
||||
The configuration is provided as a JSON literal. To remove the organization-level configuration `NULL` should be passed as the `rate_limit`.
|
||||
|
||||
##### Returns
|
||||
|
||||
This functions doesn't return any value.
|
||||
|
||||
### Client-side interface
|
||||
|
||||
For convenience there's also a client-side interface (in the client dataservices-api extension), consisting
|
||||
of public functions to get the current configuration and privileged functions to change it.
|
||||
|
||||
#### Public functions
|
||||
|
||||
These functions are accesible to non-privileged roles, and should only be executed
|
||||
using the role corresponding to a CARTO user, since that will determine the
|
||||
user and organization to which the rate limits configuration applies.
|
||||
|
||||
#### cdb_dataservices_client.cdb_service_get_rate_limit(service)
|
||||
|
||||
This function returns the rate limit configuration in effect for the specified service
|
||||
and the user corresponding to the role which makes the calls. The effective configuration
|
||||
may come from any of the configuration levels (server/organization/user); only the
|
||||
existing configuration with most precedence is returned.
|
||||
|
||||
##### Returns
|
||||
|
||||
The result is a JSON object with the configuration (`period` and `limit` attributes as explained above).
|
||||
|
||||
##### Example:
|
||||
|
||||
```
|
||||
SELECT cdb_dataservices_client.cdb_service_get_rate_limit('geocoder');
|
||||
|
||||
cdb_service_get_rate_limit
|
||||
---------------------------------
|
||||
{"limit": 1000, "period": 86400}
|
||||
(1 row)
|
||||
```
|
||||
|
||||
|
||||
#### Privileged (superuser) functions
|
||||
|
||||
Thes functions are not accessible by regular user roles, and the user and organization names must be provided as parameters.
|
||||
|
||||
#### cdb_dataservices_client.cdb_service_set_user_rate_limit(username, orgname, service, rate_limit)
|
||||
|
||||
This function sets the rate limit configuration for the user. This overrides any other configuration.
|
||||
|
||||
The configuration is provided as a JSON literal. To remove the user-level configuration `NULL` should be passed as the `rate_limit`.
|
||||
|
||||
##### Returns
|
||||
|
||||
This functions doesn't return any value.
|
||||
|
||||
##### Example
|
||||
|
||||
This will configure the geocoder service rate limit for user `myusername`, a non-organization user.
|
||||
The limit will be set at 1000 requests per day. Since the user doesn't belong to any organization,
|
||||
`NULL` will be passed to the organization argument; otherwise the name of the user's organization should
|
||||
be provided.
|
||||
|
||||
Note that the name of the geocoding services is `geocoder` and not `geocoding`.
|
||||
|
||||
```
|
||||
SELECT cdb_dataservices_client.cdb_service_set_user_rate_limit(
|
||||
'myusername',
|
||||
NULL,
|
||||
'geocoder',
|
||||
'{"limit":1000,"period":86400}'
|
||||
);
|
||||
|
||||
cdb_service_set_user_rate_limit
|
||||
---------------------------------
|
||||
|
||||
(1 row)
|
||||
```
|
||||
|
||||
#### cdb_dataservices_client.cdb_service_set_org_rate_limit(username, orgname, service, rate_limit)
|
||||
|
||||
This function sets the rate limit configuration for the organization.
|
||||
This overrides server level configuration and is overriden by user configuration if present.
|
||||
|
||||
The configuration is provided as a JSON literal. To remove the organization-level configuration `NULL` should be passed as the `rate_limit`.
|
||||
|
||||
##### Returns
|
||||
|
||||
This functions doesn't return any value.
|
||||
|
||||
##### Example
|
||||
|
||||
This will configure the geocoder service rate limit for the `myorg` organization.
|
||||
The limit will be set at 100 requests per hour.
|
||||
Note that even we're setting the default configuration for the whole organization,
|
||||
the name of a user of the organization must be provided for technical reasons.
|
||||
|
||||
```
|
||||
SELECT cdb_dataservices_client.cdb_service_set_org_rate_limit(
|
||||
'myorgadmin',
|
||||
'myorg',
|
||||
'geocoder',
|
||||
'{"limit":100,"period":3600}'
|
||||
);
|
||||
|
||||
|
||||
cdb_service_set_org_rate_limit
|
||||
---------------------------------
|
||||
|
||||
(1 row)
|
||||
```
|
||||
|
||||
#### cdb_dataservices_client.cdb_service_set_server_rate_limit(username, orgname, service, rate_limit)
|
||||
|
||||
This function sets the default rate limit configuration for all users accesing the dataservices server. This is overriden by organization of user configuration.
|
||||
|
||||
The configuration is provided as a JSON literal. To remove the organization-level configuration `NULL` should be passed as the `rate_limit`.
|
||||
|
||||
##### Returns
|
||||
|
||||
This functions doesn't return any value.
|
||||
|
||||
##### Example
|
||||
|
||||
This will configure the default geocoder service rate limit for all users
|
||||
accesing the data-services server.
|
||||
The limit will be set at 10000 requests per month.
|
||||
Note that even we're setting the default configuration for the server,
|
||||
the name of a user and the name of the corresponding organization (or NULL)
|
||||
must be provided for technical reasons.
|
||||
|
||||
```
|
||||
SELECT cdb_dataservices_client.cdb_service_set_server_rate_limit(
|
||||
'myorgadmin',
|
||||
'myorg',
|
||||
'geocoder',
|
||||
'{"limit":10000,"period":108000}'
|
||||
);
|
||||
|
||||
|
||||
cdb_service_set_server_rate_limit
|
||||
---------------------------------
|
||||
|
||||
(1 row)
|
||||
```
|
||||
Reference in New Issue
Block a user