Base
Base Class
The Base
class provides methods to interact with a Deta Base.
If you have not yet instantiated the Deta
Object, you must do so before you can use the Base
Class.
Parameter | Type | Description |
---|---|---|
d | *Deta | A pointer to a Deta instance. |
baseName | string | The name of the Base. |
Returns a pointer to a Base
instance and an error
. Possible error values:
ErrEmptyDetaInstance
: theDeta
pointer provided is emptyErrBadBaseName
: the name of the Base is invalid
ℹ️ Deta Bases are automatically created for you when you start using them.
Example:
Parameter | Type | Description |
---|---|---|
baseName | string | The name of the Base. |
host? | string | The host of the Base. |
ℹ️ Deta Bases are automatically created for you when you start using them.
Example:
Parameter | Type | Description |
---|---|---|
name | str | The name of the Base. |
host | str | None | The host of the Base. |
ℹ️ Deta Bases are automatically created for you when you start using them.
Example:
Parameter | Type | Description |
---|---|---|
name | str | The name of the Base. |
ℹ️ Deta Bases are automatically created for you when you start using them.
Example:
Put
put
is the fastest way to store an item in a Base.
If an item already exists under the given key, it will be replaced.
In the case you do not provide a key, Base will automatically generate a 12-character string as a key.
Parameter | Type | Description |
---|---|---|
item | interface{} | The item to be stored, should be a struct or a map . If the item is a struct provide the field keys for the data with JSON struct tags. The key of the item must have a JSON struct tag of key . |
Returns the key of the item stored and an error
. Possible error values:
ErrBadItem
: bad item, item is of unexpected typeErrBadRequest
: item caused a bad request response from the serverErrUnauthorized
: unuathorizedErrInternalServerError
: internal server error
ℹ️ Numbers in Base have some limits.
Example:
Parameter | Type | Description |
---|---|---|
data | DetaType | The data to be stored. |
key? | string | The key to store the data under. Will be auto generated if not provided. |
options? | PutOptions | Optional parameters. |
Returns a promise which resolves to a PutResponse
containing the item.
If the operation did not complete successfully, throws an Error
.
ℹ️ Numbers in Base have some limits.
Example:
Parameter | Type | Description |
---|---|---|
data | dict | list | str | int | float | bool | The data to be stored. |
key | str | None | The key (aka ID) to store the data under. Will be auto generated if not provided. |
expire_in | int | None | Seconds after which the item will expire in, see expiring items. |
expire_at | int | float | datetime | None | Time at which the item will expire, see expiring items. |
Returns a dict
with the item’s data.
If key
is not a non-empty string, raises a ValueError
.
If the operation did not complete successfully, raises an Exception
.
ℹ️ Numbers in Base have some limits.
Example:
Parameter | Type | Description |
---|---|---|
data | dict | list | str | int | float | bool | The data to be stored. |
key | str | None | The key (aka ID) to store the data under. Will be auto generated if not provided. |
expire_in | int | None | Seconds after which the item will expire in, see expiring items. |
expire_at | int | float | datetime | None | Time at which the item will expire, see expiring items. |
Returns an awaitable dict
with the item’s data.
If key
is not a non-empty string, raises a ValueError
.
If the operation did not complete successfully, raises an Exception
.
ℹ️ Numbers in Base have some limits.
Example:
Get
Retrieves an item by its key.
Parameter | Type | Description |
---|---|---|
key | string | The key of the item to retrieve. |
Returns a promise which resolves to a GetResponse
.
If the item is found, the response will contain the item.
If not found, the response will be null
.
Example:
Parameter | Type | Description |
---|---|---|
key | str | The key of the item to retrieve. |
If the item is found, returns a dict
with the item’s data.
Otherwise, returns None
.
If key
is not a non-empty string, raises a ValueError
.
Example:
Parameter | Type | Description |
---|---|---|
key | str | The key of the item to retrieve. |
If the item is found, returns an awaitable dict
with the item’s data.
Otherwise, returns None
.
If key
is not a non-empty string, raises a ValueError
.
Example:
Parameter | Type | Description |
---|---|---|
key | string | The key of the item to retrieve. |
dest | interface{} | The result will be stored into the value pointed by dest . |
Returns an error
. Possible error values:
ErrNotFound
: no item with such key was foundErrBadDestination
: bad destination, result could not be stored ontodest
ErrUnauthorized
: unauthorizedErrInternalServerError
: internal server error
Example:
Delete
Deletes an item by its key.
Deletes an item by its key.
Parameter | Type | Description |
---|---|---|
key | string | The key of the item to delete. |
Returns an error
. A nil
error is returned if no item was found with the provided key. Possible error values:
ErrUnauthorized
: unauthorizedErrInternalServerError
: internal server error
Example:
Deletes an item by its key.
Parameter | Type | Description |
---|---|---|
key | string | The key of the item to delete. |
Returns a promise which resolves to a DeleteResponse
.
The response will always be null
, even if the key does not exist.
Example:
Parameter | Type | Description |
---|---|---|
key | str | The key of the item to delete. |
Always returns None
, even if the key does not exist.
If key
is not a non-empty string, raises a ValueError
.
Example:
Parameter | Type | Description |
---|---|---|
key | str | The key of the item to delete. |
Always returns None
, even if the key does not exist.
If key
is not a non-empty string, raises a ValueError
.
Example:
Insert
Inserts a single item, but is different from put
in that it will throw an error of the key already exists in the Base.
ℹ️
Insert
is roughly 2 times slower thanPut
.
Parameter | Type | Description |
---|---|---|
item | interface{} | The item to be stored, similar to the item parameter in Put . |
Returns the key of the item inserted and an error
. Possible error values:
ErrConflict
: if item with provided key already existsErrBadItem
: bad item, if item is of unexpected typeErrBadRequest
: item caused a bad request response from the serverErrUnauthorized
: unauthorizedErrInternalServerError
: internal server error
Example:
ℹ️
insert
is roughly 2 times slower thanput
.
Parameter | Type | Description |
---|---|---|
data | DetaType | The data to be stored. |
key? | string | The key to store the data under. Will be auto generated if not provided. |
options? | InsertOptions | Optional parameters. |
Returns a promise which resolves to an InsertResponse
containing the item.
If the operation did not complete successfully, or the key already exists, throws an Error
.
Example:
ℹ️
insert
is roughly 2 times slower thanput
.
Parameter | Type | Description |
---|---|---|
data | dict | list | str | int | float | bool | The data to be stored. |
key | str | None | The key (aka ID) to store the data under. Will be auto generated if not provided. |
expire_in | int | None | Seconds after which the item will expire in, see expiring items. |
expire_at | int | float | datetime | None | Time at which the item will expire, see expiring items. |
Returns a dict
with the item’s data.
If key
already exists, raises an Exception
.
If key
is not a non-empty string, raises a ValueError
.
If the operation did not complete successfully, raises an Exception
.
Example:
ℹ️
insert
is roughly 2 times slower thanput
.
Parameter | Type | Description |
---|---|---|
data | dict | list | str | int | float | bool | The data to be stored. |
key | str | None | The key (aka ID) to store the data under. Will be auto generated if not provided. |
expire_in | int | None | Seconds after which the item will expire in, see expiring items. |
expire_at | int | float | datetime | None | Time at which the item will expire, see expiring items. |
Returns an awaitable dict
with the item’s data.
If key
already exists, raises an Exception
.
If key
is not a non-empty string, raises a ValueError
.
If the operation did not complete successfully, raises an Exception
.
Example:
Put Many
Puts up to 25 items at once with a single call.
Parameter | Type | Description |
---|---|---|
items | interface{} | A slice of items, each item in the slice similar to the item parameter in Put . |
Returns the list of keys of the items stored and an error
. In case of an error, none of the items are stored. Possible error values:
ErrTooManyItems
: if there are more than 25 itemsErrBadItem
: bad item/items, one or more item of unexpected typeErrBadRequest
: one or more item caused a bad request response from the serverErrUnauthorized
: unauthorizedErrInternalServerError
: internal server error
Example:
Parameter | Type | Description |
---|---|---|
items | DetaType[] | The list of items to be stored. |
options? | PutManyOptions | Optional parameters. |
Returns a promise which resolves to a PutManyResponse
containing the items.
If the operation did not complete successfully, or items
contains more than 25 items, throws an Error
.
Example:
Parameter | Type | Description |
---|---|---|
items | list | The list of items to be stored. |
expire_in | int | None | Seconds after which the item will expire in, see expiring items. |
expire_at | int | float | datetime | None | Time at which the item will expire, see expiring items. |
Returns a dict
with "processed"
and "failed"
keys containing processed and failed items.
Example:
Parameter | Type | Description |
---|---|---|
items | list | The list of items to be stored. |
expire_in | int | None | Seconds after which the item will expire in, see expiring items. |
expire_at | int | float | datetime | None | Time at which the item will expire, see expiring items. |
Returns an awaitable dict
with "processed"
and "failed"
keys containing processed and failed items.
Example:
Update
Updates an existing item.
Parameter | Type | Description |
---|---|---|
key | string | The key of the item to update. |
updates | Updates | The updates to apply to the item. |
Returns an error
. Possible error values:
ErrBadRequest
: the update operation caused a bad request response from the serverErrUnauthorized
: unauthorizedErrInternalServerError
: internal server error
Example:
Parameter | Type | Description |
---|---|---|
updates | ObjectType | An object describing the updates on the item. |
key | string | The key of the item to be updated. |
options? | UpdateOptions | Optional parameters. |
Example:
Parameter | Type | Description |
---|---|---|
updates | dict | A dictionary describing the updates on the item. |
key | str | The key of the item to be updated. |
expire_in | int | None | Seconds after which the item will expire in, see expiring items. |
expire_at | int | float | datetime | None | Time at which the item will expire, see expiring items. |
If key
is not a non-empty string, raises a ValueError
.
If the operation did not complete successfully, raises an Exception
.
Example:
Parameter | Type | Description |
---|---|---|
updates | dict | A dictionary describing the updates on the item. |
key | str | The key of the item to be updated. |
expire_in | int | None | Seconds after which the item will expire in, see expiring items. |
expire_at | int | float | datetime | None | Time at which the item will expire, see expiring items. |
If key
is not a non-empty string, raises a ValueError
.
If the operation did not complete successfully, raises an Exception
.
Example:
Update operations
Setting values is practiced through normal key-value pairs. The operation changes the values of the attributes provided in the object / dictionary if the attribute already exists. If not, it adds the attribute to the item with the corresponding value.
Other operations are implemented through methods in the Util
class / struct, accessible through the util
attribute of a Base instance.
Util
The util
attribute of a Base instance is an instance of the Util
class.
It provides utility methods for use in update operations.
Increment
Increments the value of an attribute.
The provided value can be any positive or negative integer.
The attribute’s value must be a number.
The default value is 1
.
Append
Appends to a list.
The value can be a primitive type or a array
/ list
.
Prepend
Prepends to a list.
The value can be a primitive type or an array
/ list
.
Trim
Removes an attribute from the item.
Fetch
Retrieves a list of items matching a query. It will retrieve everything if no query is provided, up to a limit of 1 MB or 1000 items.
A query is composed of a single query object or a list of query objects. In the case of a list, the indvidual queries are OR’ed.
ℹ️ Up to 1 MB of data is retrieved before filtering with the query. Thus, in some cases you might get an empty list of items and a
last
key in the response. To apply the query through all the items in your Base, you have to callfetch
untillast
is empty.
Parameter | Type | Description |
---|---|---|
i | *FetchInput | A pointer to a FetchInput |
Returns the last key
in a paginated response and an error
.
Possible error values:
ErrBadDestination
: bad destination, results could not be stored ontodest
ErrBadRequest
: the fetch request caused a bad request response from the serverErrUnauthorized
: unauthorizedErrInternalServerError
: internal server error
Example:
Parameter | Type | Description |
---|---|---|
query? | CompositeType | The query to filter the items by. |
options? | FetchOptions | Optional parameters. |
Returns promise which resolves a FetchResponse
.
Example:
Parameter | Type | Description |
---|---|---|
query | Mapping | Sequence[Mapping] | The query to filter the items by. |
limit | int | The maximum number of items you want to retreive, minimum value 1 . |
last | str | None | The last key seen in a previous paginated response. |
desc | bool | Sort items in descending order by their keys, default False . |
Returns an instance of FetchResponse
.
Example:
Parameter | Type | Description |
---|---|---|
query | Mapping | Sequence[Mapping] | The query to filter the items by. |
limit | int | The maximum number of items you want to retreive, minimum value 1 . |
last | str | None | The last key seen in a previous paginated response. |
desc | bool | Sort items in descending order by their keys, default False . |
Returns an awaitable instance of FetchResponse
.
Example:
FetchResponse
The FetchResponse
class describes the response of the fetch
method.
Attribute | Type | Description |
---|---|---|
count | int | The number of items in the response. |
last | str | None | The last key seen in the fetch response. If last is not None further items are to be retreived |
items | list | The list of items retreived. |