API
Tip
By default, Swagger UI is enabled and can be accessed at http://localhost:8080/api/docs/
Authentication#
A session must be active in order for you to be able to access collection and document endpoints.
Open session#
In the following script, the default credentials are used to open a session in the defaultdb database.
A sessionID is assigned by immudb, and this value must be included in all subsequent requests.
1sessionid=$(
2curl -X 'POST' \
3'http://localhost:8080/api/v2/authorization/session/open' \
4-H 'accept: application/json' \
5-H 'Content-Type: application/json' \
6-d '{
7 "username": "immudb",
8 "password":"immudb",
9 "database":"defaultdb"
10}' | jq -r .sessionID)Close session#
Although immudb automatically closes inactive sessions, it is a good practice to explicitly close sessions when they are not needed anymore in order to free up resources immediately.
1curl -X 'POST' \
2'http://localhost:8080/api/v2/authorization/session/close' -H "sessionID: $sessionid"Collections#
Collections allow you to store and manage related documents together, making it easier to search and retrieve relevant data.
Create collection#
Any json object can be stored in a collection, but declared fields enable indexes to be created.
Here is the script that creates a collection with two fields of type STRING and a non-unique index over one of them.
1curl -X 'POST' \
2'http://localhost:8080/api/v2/collection/mycollection' \
3-H "sessionID: $sessionid" \
4-H 'accept: application/json' \
5-H 'Content-Type: application/json' \
6-d '{
7 "fields": [
8 {"name": "name", "type": "STRING"},
9 {"name": "surname", "type": "STRING"}
10 ],
11 "indexes": [
12 {"fields": ["name"], "unique": "false"}
13 ]
14}'The available types of fields are:
- STRING
- INTEGER
- BOOLEAN
- DOUBLE
- UUID
Add field#
A new field can be added to an existing collection.
1curl -X 'POST' \
2'http://localhost:8080/api/v2/collection/mycollection/field' \
3-H "sessionID: $sessionid" \
4-H 'accept: application/json' \
5-H 'Content-Type: application/json' \
6-d '{
7 "field": {
8 "name": "active",
9 "type": "BOOLEAN"
10 }
11}'Remove field#
An existing field can be deleted. Prior to removing the field, it is necessary to remove any associated indexes.
1curl -X 'DELETE' \
2'http://localhost:8080/api/v2/collection/mycollection/field/active' \
3-H "sessionID: $sessionid"Delete collection#
It is possible to delete collections, and the physical removal of any declared index will be carried out. The raw data in the transaction commit log have not been altered, but this operation cannot be reversed.
1curl -X 'DELETE' \
2'http://localhost:8080/api/v2/collection/mycollection' \
3-H "sessionID: $sessionid"Tip
If you create lots of indexes, you may want to adjust default settings to reduce your memory footprint.
Indexing parameters, including cache-size, flush-thresholds, and max-active-snapshots, can be lowered as needed, but take into account more IO reads and writes, which may lead to poor indexing performance.
Indexes#
Collections allow you to store and manage related documents together, making it easier to search and retrieve relevant data.
Create index#
It is possible to create indexes over the declared fields in the collection.
Creating non-unique indexes is possible at any time, while creating unique ones is only possible when no documents have been stored.
1curl -X 'POST' \
2 'http://localhost:8080/api/v2/collection/mycollection/index' \
3 -H 'accept: application/json' \
4 -H "sessionID: $sessionid" \
5 -H 'Content-Type: application/json' \
6 -d '{
7 "fields": [
8 "surname"
9 ]
10}'Delete index#
It is possible to delete collections, and the physical removal of any declared index will be carried out. The raw data in the transaction commit log have not been altered, but this operation cannot be reversed.
1curl -X 'DELETE' \
2'http://localhost:8080/api/v2/collection/mycollection/index?fields=surname' \
3-H "sessionID: $sessionid"Documents#
Collections allow you to store and manage related documents together, making it easier to search and retrieve relevant data.
Insert document#
Single or multiple documents can be inserted in a single request
1curl -X 'POST' \
2'http://localhost:8080/api/v2/collection/mycollection/documents' \
3-H "sessionID: $sessionid" \
4-H 'accept: application/json' \
5-H 'Content-Type: application/json' \
6-d '{
7 "documents": [
8 {"name":"John", "surname":"Doe"},
9 {"name":"Jane", "surname":"Smith"}
10 ]
11}'Search documents#
It is possible to delete collections, and the physical removal of any declared index will be carried out. The raw data in the transaction commit log have not been altered, but this operation cannot be reversed.
1curl -X 'POST' \
2'http://localhost:8080/api/v2/collection/mycollection/documents/search' \
3-H "sessionID: $sessionid" \
4-H 'accept: application/json' \
5-H 'Content-Type: application/json' \
6-d '{
7 "query": {
8 "expressions": [
9 {
10 "fieldComparisons": [
11 {
12 "field": "name",
13 "operator": "EQ",
14 "value": "John"
15 }
16 ]
17 }
18 ]
19 },
20 "page": 1,
21 "pageSize": 10
22}'The supported operators are:
- EQ: equals to
- NE: not equals to
- LT: less than
- LE: less than or equal to
- GT: greater than
- GE: greater than or equal to
- LIKE: search using regular expressions, for example “value”:"(doc)|(flick)" would allow searching for either values containing “doc” or “flick”. The syntax of golang regexp is described in this GitHub repo .
Replace documents#
A single or multiple documents can be atomically replaced.
1curl -X 'PUT' \
2 'http://localhost:8080/api/v2/collection/mycollection/documents/replace' \
3 -H 'accept: application/json' \
4 -H "sessionID: $sessionid" \
5 -H 'Content-Type: application/json' \
6 -d '{
7 "query": {
8 "expressions": [
9 {
10 "fieldComparisons": [
11 {
12 "field": "_id",
13 "operator": "EQ",
14 "value": "6530f0fa000000000000001f86853b05"
15 }
16 ]
17 }
18 ],
19 "limit": 1
20 },
21 "document": {
22 "first_name": "John",
23 "last_name": "Doe",
24 "age": 40
25 }
26}'Delete documents#
Documents can be deleted. A document audit preserves document history and allows for retrieval of all revisions, even deleted ones.
1curl -X 'POST' \
2 'http://localhost:8080/api/v2/collection/mycollection/documents/delete' \
3 -H 'accept: application/json' \
4 -H "sessionID: $sessionid" \
5 -H 'Content-Type: application/json' \
6 -d '{
7 "query": {
8 "expressions": [
9 {
10 "fieldComparisons": [
11 {
12 "field": "first_name",
13 "operator": "EQ",
14 "value": "John"
15 },
16 {
17 "field": "last_name",
18 "operator": "EQ",
19 "value": "Doe"
20 }
21 ]
22 }
23 ],
24 "limit": 1
25 }
26}'Count documents#
It is possible to retrieve the number of documents meeting a given criteria by using the document count endpoint.
1curl -X 'POST' \
2 'http://localhost:8080/api/v2/collection/mycollection/documents/count' \
3 -H 'accept: application/json' \
4 -H "sessionID: $sessionid" \
5 -H 'Content-Type: application/json' \
6 -d '{
7 "query": {
8 "expressions": [
9 {
10 "fieldComparisons": [
11 {
12 "field": "first_name",
13 "operator": "EQ",
14 "value": "Jane"
15 }
16 ]
17 }
18 ]
19 }
20}'Audit documents#
Document revisions can be retrieved through a document audit. In auditing, all revisions are tracked and retrievable, even those that have been deleted.
In order to audit a document, it is necessary to know its unique identifier, which can be obtained by inserting or querying the document.
1curl -X 'POST' \
2 'http://localhost:8080/api/v2/collection/mycollection/document/6530f0fa000000000000001f86853b05/audit' \
3 -H 'accept: application/json' \
4 -H "sessionID: $sessionid" \
5 -H 'Content-Type: application/json' \
6 -d '{
7 "page": 1,
8 "pageSize": 10
9}'