Skip to content

Usage

This section offers an overview of the deta library, designed to interact with Deta Base, a NoSQL database service. The library is presented as a tool for integration with Clojure projects, highlighting its benefits.

Table of Contents

Getting Started

To use the deta.base namespace, include it in your project dependencies and require it in your code. The namespace utilizes clojure.string, clojure.data.json, and clj-http.client for its operations.

(ns your-namespace
 (:require [deta.base :as base]))

Exemplified Usage

Database Connection Initialization

(def db (base/base "a0abcyxzxsr_aSecretValue" "items"))

Using the put Function

Basic Usage

(base/put db {:a 1 :b 2} "item-key")
(base/put db {:a 1 :b 2}) ; The key is automatically generated on the server

Handling Non-Map Values

If the data passed to the put function is not a map, it is automatically encapsulated in a map with the key "value". This allows for flexibility in the types of data that can be stored in the database.

Return Value and Exceptions

The put function returns a map containing the inserted data. If a key is not provided, the server automatically generates one. The returned map includes the data and the generated key.

The put function throws an Exception if the data type is not supported, or if the deta-key is invalid or not provided.

Example with Non-Map Value

(base/put db "Hello, World!") ; Automatically encapsulated in {"value" "Hello, World!"}

Using the get Function

Basic Usage

(base/get db "item-key")

Return Value and Exceptions

The get function returns a map containing the retrieved data if the key exists, or nil if the key does not exist or an error occurs.

The get function throws an Exception if the deta-key is invalid or not provided, or if the key is empty or not provided.

Using the delete Function

Basic Usage

(base/delete db "item-key")

Return Value and Exceptions

The delete function does not return a meaningful value, as its purpose is to remove an item from the database. If the provided key is nil or empty, the function will throw an exception. Otherwise, it attempts to delete the item corresponding to the provided key.

The delete function throws an Exception if the project key is not provided or is invalid.

Example of Usage

(base/delete db "user-123") ; Attempts to delete the item with the key "user-123"

Using the insert Function

Basic Usage

(base/insert db {:a 1 :b 2} "item-key")
(base/insert db {:a 1 :b 2}) ; The key is automatically generated on the server

Handling Non-Map Values

If the data passed to the insert function is not a map, it is automatically encapsulated in a map with the key "value". This allows for flexibility in the types of data that can be stored in the database.

Return Value and Exceptions

The insert function returns a map containing the inserted data. If a key is not provided, the server automatically generates one. The returned map includes the data and the generated key.

The insert function throws an Exception if an item with the provided key already exists (status code 409), or if the data type is not supported, or if the deta-key is invalid or not provided.

Example with Non-Map Value

(base/insert db "Hello, World!") ; Automatically encapsulated in {"value" "Hello, World!"}

Using the fetch Function

The fetch function is a powerful tool for performing custom queries on the Deta Base. It supports pagination, sorting, and limiting results, making it ideal for efficiently retrieving large sets of data.

Basic Usage

(base/fetch db)
(base/fetch db query)
(base/fetch db query parameters)
  • db: The database connection object.
  • query: A list of queries or a single query as a string. If is empty returns all results from database. Read the Deta Base documentation to know more about queries.
  • parameters: A map of parameters that can include :limit, :last and :desc.

Parameters

  • :limit: The maximum number of items to be returned. The default is 1000.
  • :last: The key of the last item from the last query, used for pagination. The default is nil.
  • :desc: A boolean indicating whether the sorting should be descending. The default is false.

Example of Use

(base/fetch db {:name "John Doe"}) ; Basic query
(base/fetch db {:age 30} {:limit 10 :last "key"}) ; Query with limit and last
(base/fetch db {:age?r [22, 30]} {:limit 10 :desc true}) ; Query with limit and sorting mode
(base/fetch db) ; Fetching all results from current Deta Base
(base/fetch db {} {:limit 1 :last "deta-is-awesome"}) ; Fetching the first result starting from the key "deta-is-awesome"

Read the Deta Base documentation to know more about queries.

Return Value and Exceptions

The fetch function returns a map containing the number of items found (:count), the key of the last item (:last), and the list of found items (:items). If an error occurs during the query, the function will return a map with :count 0, :last nil, and :items an empty list.

Example with Query Parameters

(base/fetch db [{:age?gt 30} {:name "Gulliver"}] {:limit 10 :desc true})
; Returns: {:count 5 :last "user-123" :items [{:name "Gulliver" :age 35} ...]}

Using the update Function

The update function allows you to modify an existing item in the database by providing a key and a map of updates. This function is particularly useful for updating specific fields of an item without needing to retrieve the entire item, modify it, and then put it back into the database.

Basic Usage

(base/update db "item-key" {:set {:field "new-value"}})

This example updates the field field of the item with the key item-key to the value new-value.

Parameters

  • db: The database connection object.
  • key: The key of the item to be updated.
  • updates: A map containing the updates to be applied to the item. This map can include the following keys:
  • :set: A map of fields to be updated with new values.
  • :increment: A map of fields to be incremented by a specified amount.
  • :append: A map of fields to be appended with a specified value.
  • :prepend: A map of fields to be prepended with a specified value.
  • :delete: A list of fields to be deleted.

For information on the update payload for the base/update function, please refer to the Deta Base documentation.

Return Value and Exceptions

The update function does not return a meaningful value, as its purpose is to modify an item in the database. If the key is not provided or is empty, or if there is no item with the provided key, the function will throw an Exception.

Example of Use

(base/update db "user-123" {:set {:name "New Name" :age 31} :increment {:score 1}})

This example updates the name field of the item with the key user-123 to New Name, sets the age field to 31, and increments the score field by 1.

Use Cases

Data Insertion

The put function's ability to accept any type of data makes it versatile for various use cases. Here are examples of inserting various types of data:

(base/put db {:name "John Doe" :age 30}) ; Inserting a map
(base/put db "Hello, World!") ; Inserting a string
(base/put db 42) ; Inserting an integer
(base/put db 3.14) ; Inserting a float
(base/put db true) ; Inserting a boolean
(base/put db nil) ; Inserting nil

You can also use the base/insert command to insert data. The difference between base/put and base/insert is that base/put will insert data and update if the key already exists, while base/insert will throw an exception if the key already exists.

(base/insert db {:name "John Doe" :age 30}) ; Inserting a map
(base/insert db "Hello, World!") ; Inserting a string
(base/insert db 42) ; Inserting an integer
(base/insert db 3.14) ; Inserting a float
(base/insert db true) ; Inserting a boolean
(base/insert db nil) ; Inserting nil

Data Retrieval

To retrieve data from the database, you can use the get function. Here's an example of how to retrieve an item by its key:

(base/get db "user-123")

Data Removal

The delete function is useful for removing specific items from the database. Here's an example of how you can use this function to remove an item:

(base/delete db "item-key") ; Removes the item with the key "item-key"

Data Fetching

To fetching data from the Deta Base, you can use the fetch function. Here's an example of how to fetch an item by its name:

(base/fetch db {:name "John Doe"})

Data Updating

(base/update db "key" {:set {:name "John" :age 31 :books []}})
(base/update db "key" {:increment {:age 1}})
(base/update db "key" {:append {:books ["A Book by John Doe", "Another Book By John Doe"]}})