37 lines
1.5 KiB
Markdown
37 lines
1.5 KiB
Markdown
# Exception-Safe functions
|
|
|
|
The public API dataservices functions emit exceptions in general when an error occurs
|
|
or a limiting condition is met (e.g. quotas are exceeded).
|
|
|
|
For each public function `func` we have a internal function named `_func_exception_safe` which
|
|
acts as a wrapper to the public function, with the same signature, but captures
|
|
exceptions generated during its execution (except those due to incomplete configuration or
|
|
authentication issues) and returns NULL or empty set values in those cases.
|
|
|
|
Please note these functions are considered **not public** and therefore their API (including which exceptions are wrapped and which ones are not) may change.
|
|
|
|
Instead of raising an exception they raise warnings, hopefully containing the same information of the original exception.
|
|
|
|
## Intended Use
|
|
|
|
These functions are useful in cases when it is undesirable to rollback a transaction.
|
|
Fo example if a table is geocoded with:
|
|
|
|
```sql
|
|
UPDATE table SET the_geom=cdb_geocode_street_point(address,city,NULL,country);
|
|
```
|
|
|
|
In case of the user geocoding quota being exhausted mid-process, the user could
|
|
incur in external service expenses but any geocoded data would be lost due to the
|
|
transaction rollback.
|
|
|
|
We can avoid the problem using the corresponding exception-safe function:
|
|
|
|
```sql
|
|
UPDATE table SET the_geom=_cdb_geocode_street_point_exception_safe(address,city,NULL,country);
|
|
```
|
|
|
|
# Addition Information
|
|
|
|
See https://github.com/CartoDB/dataservices-api/issues/314 for more information.
|