Indexes

Sorted sets#

On top of the key value store immudb provides secondary indexes to help developers to handle complex queries.

The sorted set data type provides a simple secondary index that can be created with immudb. This data structure contains a set of references to other key-value entries. Elements of this set are ordered using a floating-point score specified for each element upon insertion. Entries having equal score will have the order in which they were inserted into the set.

Note: The score type is a 64-bit floating point number to support a large number of uses cases. 64-bit floating point gives a lot of flexibility and dynamic range, at the expense of having only 53-bits of integer. When a 64-bit integer is cast to a float value there could be a loss of precision, in which case the order of entries having same float64 score value will be determined by the insertion order.

The KV entry referenced in the set can be bound to a specific transaction id - such entry is called a bound reference. A bound reference will always get the value for the key at a specific transaction instead of the most recent value, including a case where one set contains multiple values for the same key but for different transactions. That way, sets allow optimal access to historical data using a single immudb read operation.

Note: If a compound operation is executed with the ExecAll call, a bound entry added to the set can reference a key created/updated in the same ExecAll call. To make such an operation, set the BoundRef value to true and the AtTx value to 0.

Inserting entries into sets can be done using the following operations: ZAdd, VerifiedZAdd, ZAddAt, VerifiedZAddAt, ExecAll. Those operations accept the following parameters:

Set: the name of the collection
Score: entry score used to order items within the set
Key: the key of entry to be added to the set
AtTx: for bound references, a transaction id at which the value will be read, if set to 0 for ExecAll operation, current transaction id will be used. Optional
BoundRef: if set to true, this will be a reference bound to a specific transaction. Optional
NoWait: if set to true, don’t wait for indexing to be finished after adding this entry

Reading data from the set can be done using the following operations: ZScan, StreamZScan. Those operations accept the following parameters:

Set: the name of the collection
SeekKey: initial key for the first entry in the iteration. Optional
SeekScore: the min or max score for the first entry in the iteration, depending on Desc value. Optional
SeekAtTx: the tx id for the first entry in the iteration. Optional
InclusiveSeek: the element resulting from the combination of the SeekKey SeekScore and SeekAtTx is returned with the result. Optional
Desc: If set to true, entries will be returned in an descending (reversed) order. Optional
SinceTx: immudb will wait that the transaction provided by SinceTx be processed. Optional
NoWait: when true scan doesn’t wait that txSinceTx is processed. Optional
MinScore: minimum score filter. Optional
MaxScore: maximum score filter. Optional
Limit: maximum number of returned items. Optional

Note: issuing a ZScan or StreamZScan operation will by default wait for the index to be up-to-date. To avoid waiting for the index (and thus to allow reading the data from some older state), set the SinceTx to a very high value exceeding the most recent transaction id (e.g. maximum int value) and set NoWait to true.

go  1package main
  2
  3import (
"context"
"encoding/json"
"fmt"
"log"
"math"
  9
"github.com/codenotary/immudb/pkg/api/schema"
immudb "github.com/codenotary/immudb/pkg/client"
 12)
 13
 14func main() {
opts := immudb.DefaultOptions().
WithAddress("localhost").
WithPort(3322)
 18
client := immudb.NewClient().WithOptions(opts)
err := client.OpenSession(
context.TODO(),
[]byte(`immudb`),
[]byte(`immudb`),
"defaultdb",
)
if err != nil {
log.Fatal(err)
}
 29
defer client.CloseSession(context.TODO())
 31
i1, err := client.Set(
 33
context.TODO(),
[]byte(`user1`),
[]byte(`user1@mail.com`),
)
if err != nil {
log.Fatal(err)
}
i2, err := client.Set(
context.TODO(),
[]byte(`user2`),
[]byte(`user2@mail.com`),
)
if err != nil {
log.Fatal(err)
}
i3, err := client.Set(
context.TODO(),
[]byte(`user3`),
[]byte(`user3@mail.com`),
)
if err != nil {
log.Fatal(err)
}
i4, err := client.Set(
context.TODO(),
[]byte(`user3`),
[]byte(`another-user3@mail.com`),
)
if err != nil {
log.Fatal(err)
}
 65
if _, err = client.ZAddAt(
context.TODO(),
[]byte(`age`), 25, []byte(`user1`), i1.Id,
); err != nil {
log.Fatal(err)
}
if _, err = client.ZAddAt(
context.TODO(),
[]byte(`age`), 36, []byte(`user2`), i2.Id,
); err != nil {
log.Fatal(err)
}
if _, err = client.ZAddAt(
context.TODO(),
[]byte(`age`), 36, []byte(`user3`), i3.Id,
); err != nil {
log.Fatal(err)
}
if _, err = client.ZAddAt(
context.TODO(),
[]byte(`age`), 54, []byte(`user3`), i4.Id,
); err != nil {
log.Fatal(err)
}
 90
zscanOpts1 := &schema.ZScanRequest{
Set:      []byte(`age`),
SinceTx:  math.MaxUint64,
NoWait:   true,
MinScore: &schema.Score{Score: 36},
}
 97
the36YearsOldList, err := client.ZScan(context.TODO(), zscanOpts1)
if err != nil {
log.Fatal(err)
}
s, _ := json.MarshalIndent(the36YearsOldList, "", "\t")
fmt.Print(string(s))
104
oldestReq := &schema.ZScanRequest{
Set:       []byte(`age`),
SeekKey:   []byte{0xFF},
SeekScore: math.MaxFloat64,
SeekAtTx:  math.MaxUint64,
Limit:     1,
Desc:      true,
SinceTx:   math.MaxUint64,
NoWait:    true,
}
115
oldest, err := client.ZScan(context.TODO(), oldestReq)
if err != nil {
log.Fatal(err)
}
s, _ = json.MarshalIndent(oldest, "", "\t")
fmt.Print(string(s))
122}

Java

java 1package io.codenotary.immudb.helloworld;
 2
 3import java.util.Iterator;
 4
 5import io.codenotary.immudb4j.FileImmuStateHolder;
 6import io.codenotary.immudb4j.ImmuClient;
 7import io.codenotary.immudb4j.ZEntry;
 8
 9public class App {
10
11    public static void main(String[] args) {
12
13        ImmuClient client = null;
14
15        try {
16
17            FileImmuStateHolder stateHolder = FileImmuStateHolder.newBuilder()
18                    .withStatesFolder("./immudb_states")
19                    .build();
20
21            client = ImmuClient.newBuilder()
22                    .withServerUrl("127.0.0.1")
23                    .withServerPort(3322)
24                    .withStateHolder(stateHolder)
25                    .build();
26
27            client.openSession("defaultdb", "immudb", "immudb");
28
29            byte[] value1 = { 0, 1, 2, 3 };
30            byte[] value2 = { 4, 5, 6, 7 };
31
32            client.set("key1", value1);
33            client.set("key2", value2);
34
35            client.zAdd("set1", "key1", 1);
36
37            client.zAdd("set1", "key2", 2);
38
39            Iterator<ZEntry> it = client.zScan("set1");
40           
41            while (it.hasNext()) {
42                ZEntry zentry = it.next();
43                System.out.format("('%s', '%f')\n", new String(zentry.getKey()), zentry.getScore());
44            }
45
46            client.closeSession();
47
48        } catch (Exception e) {
49            e.printStackTrace();
50        } finally {
51            if (client != null) {
52                try {
53                    client.shutdown();
54                } catch (InterruptedException e) {
55                    e.printStackTrace();
56                }
57            }
58        }
59
60    }
61
62}

.NET

csharp 1var client = new ImmuClient();
 2await client.Open("immudb", "immudb", "defaultdb");
 3
 4byte[] value1 = { 0, 1, 2, 3 };
 5byte[] value2 = { 4, 5, 6, 7 };
 6
 7try
 8{
 9    await client.Set("zadd1", value1);
10    await client.Set("zadd2", value2);
11}
12catch (CorruptedDataException e)
13{
14   Console.WriteLine("A CorruptedDataException occurred.");
15}
16
17try
18{
19    await client.ZAdd("set1", "zadd1", 1);
20    await client.ZAdd("set1", "zadd2", 2);
21
22    await client.ZAdd("set2", "zadd1", 2);
23    await client.ZAdd("set2", "zadd2", 1);
24}
25catch (CorruptedDataException e)
26{
27    Console.WriteLine("A CorruptedDataException occurred");
28}
29
30List<ZEntry> zScan1 = await client.ZScan("set1", 5, false);
31
32Console.WriteLine(zScan1.Count);
33
34await client.Close();

Python

python 1from immudb import ImmudbClient
 2
 3URL = "localhost:3322"  # immudb running on your machine
 4LOGIN = "immudb"        # Default username
 5PASSWORD = "immudb"     # Default password
 6DB = b"defaultdb"       # Default database name (must be in bytes)
 7
 8def main():
 9    client = ImmudbClient(URL)
10    client.login(LOGIN, PASSWORD, database = DB)
11    client.set(b"user1", b"user1@mail.com")
12    client.set(b"user2", b"user2@mail.com")
13    client.set(b"user3", b"user3@mail.com")
14    client.set(b"user4", b"user3@mail.com")
15
16    client.zAdd(b"age", 100, b"user1")
17    client.zAdd(b"age", 101, b"user2")
18    client.zAdd(b"age", 99, b"user3")
19    client.zAdd(b"age", 100, b"user4")
20
21    scanResult = client.zScan(b"age", b"", 0, 0, True, 50, False, 100, 101)
22    print(scanResult)   # Shows records with 'age' 100 <= score < 101
23                        # with descending order and limit = 50
24
25if __name__ == "__main__":
26    main()

Node.js

ts 1import ImmudbClient from 'immudb-node'
 2import Parameters from 'immudb-node/types/parameters'
 3
 4const IMMUDB_HOST = '127.0.0.1'
 5const IMMUDB_PORT = '3322'
 6const IMMUDB_USER = 'immudb'
 7const IMMUDB_PWD = 'immudb'
 8
 9const cl = new ImmudbClient({ host: IMMUDB_HOST, port: IMMUDB_PORT });
10
11(async () => {
  await cl.login({ user: IMMUDB_USER, password: IMMUDB_PWD })
13
  const { id: id1 } = await cl.set({ key: 'user1', value: 'user1@mail.com' })
  const { id: id2 } = await cl.set({ key: 'user2', value: 'user2@mail.com' })
  const { id: id3 } = await cl.set({ key: 'user3', value: 'user3@mail.com' })
  const { id: id4 } = await cl.set({ key: 'user3', value: 'another-user3@mail.com' })
18
  const zAddAtReq1: Parameters.ZAddAt = {
      set: 'age',
      score: 25,
      key: 'user1',
      attx: id1
  }
  const zAddAtRes1 = await cl.zAddAt(zAddAtReq1)
  const zAddAtReq2: Parameters.ZAddAt = {
      set: 'age',
      score: 36,
      key: 'user2',
      attx: id2
  }
  const zAddAtRes2 = await cl.zAddAt(zAddAtReq2)
  const zAddAtReq3: Parameters.ZAddAt = {
      set: 'age',
      score: 36,
      key: 'user3',
      attx: id3
  }
  const zAddAtRes3 = await cl.zAddAt(zAddAtReq3)
  const zAddAtReq4: Parameters.ZAddAt = {
      set: 'age',
      score: 54,
      key: 'user4',
      attx: id4
  }
  const zAddAtRes4 = await cl.zAddAt(zAddAtReq4)
47
  const zScanReq: Parameters.ZScan = {
      set: 'age',
      sincetx: 0,
      nowait: true,
      minscore: {
          score: 36
      }
  }
  const zScanRes = await cl.zScan(zScanReq)
  console.log('success: zScan all 36-years-old users', zScanRes)
58})()

Others

If you’re using another development language, please refer to the immugw option.

Edit this page on GitHub Last updated 2 September 2026