cartodb4/dataservices-api
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

applied copyedits to quote info docs

Browse Source
This commit is contained in:
csobier
2017-01-03 08:35:57 -05:00
parent 07616c468a
commit dae8021efe
1 changed files with 19 additions and 32 deletions
Download Patch File Download Diff File Expand all files Collapse all files
doc/quota_information.md
+19 -32
View File
@@ -14,9 +14,9 @@ Quota consumption is calculated based on the number of request made for each fun
* 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 * 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 ## Quota Information Functions
Two functions are available to obtain information about available services quotas. There are several SQL functions that you can run to obtain quota information about your services.
## cdb_service_quota_info() ## cdb_service_quota_info()
@@ -31,19 +31,19 @@ Name | Type | Description
`service` | `text` | Type of service. `service` | `text` | Type of service.
`monthly_quota` | `numeric` | Quota available to the user (number of calls) per monthly period. `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. `used_quota` | `numeric` | Quota used by the user in the present period.
`soft_limit` | `boolean` | True if the user has *soft-limit* quota `soft_limit` | `boolean` | Set to `True`, if the user has *soft-limit* quota.
`provider` | `text` | Service provider for this type of service `provider` | `text` | Service provider for this type of service.
Service types: Service Types:
* `'isolines'` [Isoline/Isochrones (isochrone/isodistance lines) service](https://carto.com/docs/carto-engine/dataservices-api/isoline_functions/) * `'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) * `'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/) * `'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) * `'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: **Notes**
Users who have *soft-quota* activated never run out of quota, but they may incurr into extra Users who have *soft-quota* activated never run out of quota, but they may incur extra
expenses when the regular quota is exceeded. expenses when the regular quota is exceeded.
A zero value of `monthly_quota` indicates that the service has not been activated for the user. A zero value of `monthly_quota` indicates that the service has not been activated for the user.
@@ -67,31 +67,24 @@ Result:
``` ```
In this case we notice the user has no access to the observatory services, 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.
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) ## cdb_enough_quota(service text ,input_size numeric)
This function is useful to check if enough quota is available for completing a job. This function is useful to check if enough quota is available for completing a job.
This is specially relevant if a number of service calls are to be performed inside a transaction: 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.
if any of the calls fails due to exceeded quota the transaction will be rolled back, resulting
in some quota being consumed but no saved results from the services consumed.
In the case of of calling repeatedly quota-consuming functions (e.g. to geocode a whole table) it is **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.
extremely important to first check if enough quota is available to complete the job using
this function.
Mind that some services consume more than one credit per row/call. 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.
E.g: isolines with more than one range/track would consume (N rows x M ranges) credits and therefore the input size should be N x M.
#### Arguments #### Arguments
Name | Type | Description Name | Type | Description
------------ | --------- | ----------- ------------ | --------- | -----------
`service` | `text` | Service to check; see the list of valid services above `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 `input_size` | `numeric` | Number of service calls required, i.e. size of the input to be processed.
#### Returns #### Returns
@@ -101,9 +94,7 @@ insufficient quota.
#### Example #### Example
Imagine you wish to geocode a whole table. Suppose you want to geocode a whole table. In order to check that you have enough quota, and avoid a "quota exhausted" exceptio, first find out how many records you need to geocode:
In order to check that you have enough quota and avoid a "quota exhausted" exception
you should first find out how many records you need to geocode:
```sql ```sql
SELECT COUNT(*) FROM {tablename} WHERE {street_name_column} IS NOT NULL; SELECT COUNT(*) FROM {tablename} WHERE {street_name_column} IS NOT NULL;
@@ -118,15 +109,14 @@ Result: here's a sample result of 10000 records:
(1 row) (1 row)
``` ```
Now you can find out if there's enough quota to complete this job. In this case The result shows how much quota is needed to complete this job. In this case,
each call to `cdb_geocode_street_point` will consume one quota credit, so we need 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.
as many credits as rows to be geocoded.
```sql ```sql
SELECT cdb_enough_quota('hires_geocoder', {number_of_records}); SELECT cdb_enough_quota('hires_geocoder', {number_of_records});
``` ```
The result should be similar to this: The result is similar to the following:
``` ```
cdb_enough_quota cdb_enough_quota
@@ -134,12 +124,9 @@ The result should be similar to this:
t t
``` ```
If the result of this query is *true* (`'t'`) you can safely proceed; if you get 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.
a *false* value (`'f'`) you should avoid the processing; use `cdb_service_quota_info` as explained
above to obtain further information.
Don't forget to apply any filtering conditions you've used to **Note:** Remember to apply any filtering conditions that you used to count the records (in this case, `{street_name_column} IS NOT NULL`):
count the records (in our case `{street_name_column} IS NOT NULL`):
```sql ```sql