Queries and history

The fundamental property of immudb is that it’s an append-only database. This means that an update is a new insert of the same key with a new value. It’s possible to retrieve all the values for a particular key with the history command.

History accepts the following parameters:

  • Key: a key of an item
  • Offset: the starting index (excluded from the search). Optional
  • Limit: maximum returned items. Optional
  • Desc: items are returned in reverse order. Optional
  • SinceTx:
  1.     client.Set(ctx, []byte(`hello`), []byte(`immutable world`))
  2.     client.Set(ctx, []byte(`hello`), []byte(`immudb`))
  4.     req := &schema.HistoryRequest{
  5.         Key: []byte(`hello`),
  6.     }
  8.     entries, err := client.History(ctx, req)
  9.     if  err != nil {
  10.         log.Fatal(err)
  11.     }
  13.     fmt.Printf("Successfully retrieved %d entries for key %s\n", len(entries), req.Key)
  1. try {
  2.     immuClient.set("hello", value1);
  3.     immuClient.set("hello", value2);
  4. } catch (CorruptedDataException e) {
  5.     // ...
  6. }
  8. List<KV> historyResponse1 = immuClient.history("hello", 10, 0, false, 1);

Note that, similar with many other methods, history method is overloaded to allow different kinds/set of parameters.

This feature is not yet supported or not documented. Do you want to make a feature request or help out? Open an issue on Python sdk github projectQueries and history - 图1 (opens new window)

  1. import ImmudbClient from 'immudb-node'
  2. import Parameters from 'immudb-node/types/parameters'
  4. const IMMUDB_HOST = '127.0.0.1'
  5. const IMMUDB_PORT = '3322'
  6. const IMMUDB_USER = 'immudb'
  7. const IMMUDB_PWD = 'immudb'
  9. const cl = new ImmudbClient({ host: IMMUDB_HOST, port: IMMUDB_PORT });
  11. (async () => {
  12.     await cl.login({ user: IMMUDB_USER, password: IMMUDB_PWD })
  14.     const key = 'hello'
  16.     await cl.set({ key, value: 'immutable world' })
  17.     await cl.set({ key, value: 'immudb' })
  19.     const historyReq: Parameters.History = {
  20.         key
  21.     }
  22.     const historyRes = cl.history(historyReq)
  23.     console.log('success: history', historyRes)
  24. })()

This feature is not yet supported or not documented. Do you want to make a feature request or help out? Open an issue on .Net sdk github projectQueries and history - 图2 (opens new window)

If you’re using another development language, please read up on our immugwQueries and history - 图3 (opens new window) option.

Counting

Counting entries is not supported at the moment.

This feature is not yet supported or not documented. Do you want to make a feature request or help out? Open an issue on Go sdk github projectQueries and history - 图4 (opens new window)

This feature is not yet supported or not documented. Do you want to make a feature request or help out? Open an issue on Java sdk github projectQueries and history - 图5 (opens new window)

This feature is not yet supported or not documented. Do you want to make a feature request or help out? Open an issue on Python sdk github projectQueries and history - 图6 (opens new window)

This feature is not yet supported or not documented. Do you want to make a feature request or help out? Open an issue on Node.js sdk github projectQueries and history - 图7 (opens new window)

This feature is not yet supported or not documented. Do you want to make a feature request or help out? Open an issue on .Net sdk github projectQueries and history - 图8 (opens new window)

If you’re using another development language, please read up on our immugwQueries and history - 图9 (opens new window) option.

Scan

The scan command is used to iterate over the collection of elements present in the currently selected database. Scan accepts the following parameters:

  • Prefix: prefix. If not provided all keys will be involved. Optional
  • SeekKey: initial key for the first entry in the iteration. Optional
  • Desc: DESC or ASC sorting order. Optional
  • Limit: maximum returned items. Optional
  • SinceTx: immudb will wait that the transaction provided by SinceTx be processed. Optional
  • NoWait: Default false. When true scan doesn’t wait for the index to be fully generated and returns the last indexed value. Optional

To gain speed it’s possible to specify noWait=true. The control will be returned to the caller immediately, without waiting for the indexing to complete. When noWait is used, keep in mind that the returned data may not be yet up to date with the inserted data, as the indexing might not have completed.

An ordinary scan command and a reversed one.

  1.     client.Set(ctx, []byte(`aaa`), []byte(`item1`))
  2.     client.Set(ctx, []byte(`bbb`), []byte(`item2`))
  3.     client.Set(ctx, []byte(`abc`),[]byte(`item3`))
  5.     scanReq := &schema.ScanRequest{
  6.         Prefix:  []byte(`a`),
  7.     }
  9.     list, err := client.Scan(ctx, scanReq)
  10.     if err != nil {
  11.         log.Fatal(err)
  12.     }
  13.     fmt.Printf("%v\n", list)
  14.     scanReq1 := &schema.ScanRequest{
  15.         SeekKey: []byte{0xFF},
  16.         Prefix:  []byte(`a`),
  17.         Desc:    true,
  18.     }
  20.     list, err = client.Scan(ctx, scanReq1)
  21.     if err != nil {
  22.         log.Fatal(err)
  23.     }
  24.     fmt.Printf("%v\n", list)
  26.     // scan on all key  values on the current database, with a fresh snapshot
  27.     scanReq2 := &schema.ScanRequest{
  28.         SeekKey: []byte{0xFF},
  29.         Desc:    true,
  30.         SinceTx: math.MaxUint64,
  31.     }
  33.     list, err = client.Scan(ctx, scanReq2)
  34.     if err != nil {
  35.         log.Fatal(err)
  36.     }
  37.     fmt.Printf("%v\n", list)
  1. byte[] value1 = {0, 1, 2, 3};
  2. byte[] value2 = {4, 5, 6, 7};
  4. try {
  5.     immuClient.set("scan1", value1);
  6.     immuClient.set("scan2", value2);
  7. } catch (CorruptedDataException e) {
  8.     // ...
  9. }
  11. // Example of using scan(prefix, sinceTxId, limit, desc).
  12. List<KV> scanResult = immuClient.scan("scan", 1, 5, false);
  13. // We expect two entries in the result.

scan is an overloaded method, therefore multiple flavours of it with different parameter options exist.

This feature is not yet supported or not documented. Do you want to make a feature request or help out? Open an issue on Python sdk github projectQueries and history - 图10 (opens new window)

  1. import ImmudbClient from 'immudb-node'
  2. import Parameters from 'immudb-node/types/parameters'
  4. const IMMUDB_HOST = '127.0.0.1'
  5. const IMMUDB_PORT = '3322'
  6. const IMMUDB_USER = 'immudb'
  7. const IMMUDB_PWD = 'immudb'
  9. const cl = new ImmudbClient({ host: IMMUDB_HOST, port: IMMUDB_PORT });
  11. (async () => {
  12.     await cl.login({ user: IMMUDB_USER, password: IMMUDB_PWD })
  14.     await cl.set({ key: 'aaa', value: 'item1' })
  15.     await cl.set({ key: 'bbb', value: 'item2' })
  16.     await cl.set({ key: 'abc', value: 'item3' })
  18.     const scanReq: Parameters.Scan = {
  19.         prefix: 'a',
  20.         desc: false,
  21.         limit: 0,
  22.         sincetx: 0
  23.     }
  24.     const scanRes = await cl.scan(scanReq)
  25.     console.log('success: scan', scanRes)
  27.     const scanReq1: Parameters.Scan = {
  28.         prefix: 'a',
  29.         desc: true,
  30.         limit: 0,
  31.         sincetx: 0
  32.     }
  33.     const scanRes1 = await cl.scan(scanReq1)
  34.     console.log('success: scan', scanRes1)
  35. })()

Example with an offset:

  1. import ImmudbClient from 'immudb-node'
  2. import Parameters from 'immudb-node/types/parameters'
  4. const IMMUDB_HOST = '127.0.0.1'
  5. const IMMUDB_PORT = '3322'
  6. const IMMUDB_USER = 'immudb'
  7. const IMMUDB_PWD = 'immudb'
  9. const cl = new ImmudbClient({ host: IMMUDB_HOST, port: IMMUDB_PORT });
  11. (async () => {
  12.     await cl.login({ user: IMMUDB_USER, password: IMMUDB_PWD })
  14.     await cl.set({ key: 'aaa', value: 'item1' })
  15.     await cl.set({ key: 'bbb', value: 'item2' })
  16.     await cl.set({ key: 'abc', value: 'item3' })
  18.     const scanReq: Parameters.Scan = {
  19.         seekkey: '',
  20.         prefix: '',
  21.         desc: true,
  22.         limit: 0,
  23.         sincetx: 0
  24.     }
  25.     const scanRes = await cl.scan(scanReq)
  26.     console.log('success: scan', scanRes)
  28.     const scanReq1: Parameters.Scan = {
  29.         seekkey: 'bbb',
  30.         prefix: '',
  31.         desc: true,
  32.         limit: 0,
  33.         sincetx: 0
  34.     }
  35.     const scanRes1 = await cl.scan(scanReq1)
  36.     console.log('success: scan', scanRes1)
  38.     const scanReq2: Parameters.Scan = {
  39.         seekkey: 'b',
  40.         prefix: 'b',
  41.         desc: true,
  42.         limit: 0,
  43.         sincetx: 0
  44.     }
  45.     const scanRes2 = await cl.scan(scanReq2)
  46.     console.log('success: scan', scanRes2)
  47. })()

This feature is not yet supported or not documented. Do you want to make a feature request or help out? Open an issue on .Net sdk github projectQueries and history - 图11 (opens new window)

If you’re using another development language, please read up on our immugwQueries and history - 图12 (opens new window) option.

References

SetReference is like a “tag” operation. It appends a reference on a key/value element. As a consequence, when we retrieve that reference with a Get or VerifiedGet the value retrieved will be the original value associated with the original key. Its VerifiedReference counterpart is the same except that it also produces the inclusion and consistency proofs.

SetReference and VerifiedSetReference

  1.     _, err = client.Set(ctx, []byte(`firstKey`),[]byte(`firstValue`))
  2.     if err != nil {
  3.         log.Fatal(err)
  4.     }
  5.     reference, err := client.SetReference(ctx, []byte(`myTag`), []byte(`firstKey`))
  6.     if err != nil {
  7.         log.Fatal(err)
  8.     }
  10.     fmt.Printf("%v\n", reference)
  11.     firstItem, err := client.Get(ctx, []byte(`myTag`))
  12.     if err != nil {
  13.         log.Fatal(err)
  14.     }
  15.     fmt.Printf("%v\n", firstItem)

Example with verifications

  1.     _, err = client.Set(ctx, []byte(`secondKey`),[]byte(`secondValue`))
  2.     if err != nil {
  3.         log.Fatal(err)
  4.     }
  5.     reference, err = client.VerifiedSetReference(ctx, []byte(`mySecondTag`), []byte(`secondKey`))
  6.     if err != nil {
  7.         log.Fatal(err)
  8.     }
  9.     fmt.Printf("%v\n", reference)
  11.     secondItem, err := client.Get(ctx, []byte(`mySecondTag`))
  12.     if err != nil {
  13.         log.Fatal(err)
  14.     }
  15.     fmt.Printf("%v\n", secondItem)
  1. byte[] key = "testRef".getBytes(StandardCharsets.UTF_8);
  2. byte[] val = "abc".getBytes(StandardCharsets.UTF_8);
  4. TxMetadata txMd = null;
  5. try {
  6.     txMd = immuClient.set(key, val);
  7. } catch (CorruptedDataException e) {
  8.     // ...
  9. }
  11. byte[] ref1Key = "ref1_to_testRef".getBytes(StandardCharsets.UTF_8);
  12. byte[] ref2Key = "ref2_to_testRef".getBytes(StandardCharsets.UTF_8);
  14. try {
  15.     txMd = immuClient.setReference(ref1Key, key);
  16. } catch (CorruptedDataException e) {
  17.     // ...
  18. }
  20. try {
  21.     txMd = immuClient.verifiedSetReference(ref2Key, key);
  22. } catch (VerificationException e) {
  23.     // ...
  24. }

This feature is not yet supported or not documented. Do you want to make a feature request or help out? Open an issue on Python sdk github projectQueries and history - 图13 (opens new window)

  1. import ImmudbClient from 'immudb-node'
  2. import Parameters from 'immudb-node/types/parameters'
  4. const IMMUDB_HOST = '127.0.0.1'
  5. const IMMUDB_PORT = '3322'
  6. const IMMUDB_USER = 'immudb'
  7. const IMMUDB_PWD = 'immudb'
  9. const cl = new ImmudbClient({ host: IMMUDB_HOST, port: IMMUDB_PORT });
  11. (async () => {
  12.     await cl.login({ user: IMMUDB_USER, password: IMMUDB_PWD })
  14.     const setReq: Parameters.Set = {
  15.         key: 'firstKey',
  16.         value: 'firstValue'
  17.     }
  18.     await cl.set(setReq)
  20.     const referenceReq: Parameters.SetReference = {
  21.         key: 'myTag',
  22.         referencedKey: 'firstKey'
  23.     }
  24.     const referenceRes = await cl.setReference(referenceReq)
  25.     console.log('success: setReference', referenceRes)
  27.     const getReq: Parameters.Get = {
  28.         key: 'myTag'
  29.     }
  30.     const getRes = await cl.get(getReq)
  31.     console.log('success: get by reference', getRes)
  32. })()

Example with verifications

  1. import ImmudbClient from 'immudb-node'
  2. import Parameters from 'immudb-node/types/parameters'
  4. const IMMUDB_HOST = '127.0.0.1'
  5. const IMMUDB_PORT = '3322'
  6. const IMMUDB_USER = 'immudb'
  7. const IMMUDB_PWD = 'immudb'
  9. const cl = new ImmudbClient({ host: IMMUDB_HOST, port: IMMUDB_PORT });
  11. (async () => {
  12.     await cl.login({ user: IMMUDB_USER, password: IMMUDB_PWD })
  14.     const setReq: Parameters.Set = {
  15.         key: 'firstKey',
  16.         value: 'firstValue'
  17.     }
  18.     await cl.set(setReq)
  20.     const verifiedReferenceReq: Parameters.SetReference = {
  21.         key: 'myTag',
  22.         referencedKey: 'firstKey'
  23.     }
  24.     const verifiedReferenceRes = await cl.verifiedSetReference(verifiedReferenceReq)
  25.     console.log('success: verifiedSetReference', verifiedReferenceRes)
  27.     const getReq: Parameters.Get = {
  28.         key: 'myTag'
  29.     }
  30.     const getRes = await cl.get(getReq)
  31.     console.log('success: get by reference', getRes)
  32. })()

This feature is not yet supported or not documented. Do you want to make a feature request or help out? Open an issue on .Net sdk github projectQueries and history - 图14 (opens new window)

If you’re using another development language, please read up on our immugwQueries and history - 图15 (opens new window) option.

GetReference and VerifiedGetReference

When reference is resolved with get or verifiedGet in case of multiples equals references the last reference is returned.

  1.     _, err = client.Set(ctx, []byte(`secondKey`),[]byte(`secondValue`))
  2.     if err != nil {
  3.         log.Fatal(err)
  4.     }
  5.     _, err = client.Set(ctx, []byte(`secondKey`),[]byte(`thirdValue`))
  6.     if err != nil {
  7.         log.Fatal(err)
  8.     }
  9.     reference, err = client.VerifiedSetReference(ctx, []byte(`myThirdTag`), []byte(`secondKey`))
  10.     if err != nil {
  11.         log.Fatal(err)
  12.     }
  13.     fmt.Printf("%v\n", reference)
  15.     thirdItem, err := client.Get(ctx, []byte(`myThirdTag`))
  16.     if err != nil {
  17.         log.Fatal(err)
  18.     }
  19.     fmt.Printf("%v\n", thirdItem)

This feature is not yet supported or not documented. Do you want to make a feature request or help out? Open an issue on Java sdk github projectQueries and history - 图16 (opens new window)

This feature is not yet supported or not documented. Do you want to make a feature request or help out? Open an issue on Python sdk github projectQueries and history - 图17 (opens new window)

  1. import ImmudbClient from 'immudb-node'
  2. import Parameters from 'immudb-node/types/parameters'
  4. const IMMUDB_HOST = '127.0.0.1'
  5. const IMMUDB_PORT = '3322'
  6. const IMMUDB_USER = 'immudb'
  7. const IMMUDB_PWD = 'immudb'
  9. const cl = new ImmudbClient({ host: IMMUDB_HOST, port: IMMUDB_PORT });
  11. (async () => {
  12.     await cl.login({ user: IMMUDB_USER, password: IMMUDB_PWD })
  14.     const setReq: Parameters.Set = {
  15.         key: 'firstKey',
  16.         value: 'firstValue'
  17.     }
  18.     await cl.set(setReq)
  19.     const setReq1: Parameters.Set = {
  20.         key: 'secondKey',
  21.         value: 'secondValue'
  22.     }
  23.     await cl.set(setReq1)
  25.     const verifiedReferenceReq: Parameters.SetReference = {
  26.         key: 'myTag',
  27.         referencedKey: 'firstKey'
  28.     }
  29.     await cl.verifiedSetReference(verifiedReferenceReq)
  30.     const verifiedReferenceReq1: Parameters.SetReference = {
  31.         key: 'myTag',
  32.         referencedKey: 'secondKey'
  33.     }
  34.     await cl.verifiedSetReference(verifiedReferenceReq1)
  36.     const getReq: Parameters.Get = {
  37.         key: 'myTag'
  38.     }
  39.     const getSecondItemRes = await cl.get(getReq)
  40.     console.log('success: get by second reference', getSecondItemRes)
  41. })()

This feature is not yet supported or not documented. Do you want to make a feature request or help out? Open an issue on .Net sdk github projectQueries and history - 图18 (opens new window)

If you’re using another development language, please read up on our immugwQueries and history - 图19 (opens new window) option.

Resolving reference with transaction id

It’s possible to bind a reference to a key on a specific transaction using SetReferenceAt and VerifiedSetReferenceAt

  1.     meta, err := client.Set(ctx, []byte(`secondKey`),[]byte(`secondValue`))
  2.     if err != nil {
  3.         log.Fatal(err)
  4.     }
  5.     _ , err = client.Set(ctx, []byte(`secondKey`),[]byte(`thirdValue`))
  6.     if err != nil {
  7.         log.Fatal(err)
  8.     }
  9.     reference, err = client.VerifiedSetReferenceAt(ctx, []byte(`myThirdTag`), []byte(`secondKey`), meta.Id )
  10.     if err != nil {
  11.         log.Fatal(err)
  12.     }
  13.     fmt.Printf("%v\n", reference)
  15.     thirdItem, err := client.Get(ctx, []byte(`myThirdTag`))
  16.     if err != nil {
  17.         log.Fatal(err)
  18.     }
  19.     fmt.Printf("%v\n", thirdItem)
  1. byte[] key = "testRef".getBytes(StandardCharsets.UTF_8);
  2. byte[] val = "abc".getBytes(StandardCharsets.UTF_8);
  4. byte[] refKey = "ref1_to_testRef".getBytes(StandardCharsets.UTF_8);
  5. TxMetadata setTxMd = null;
  7. try {
  8.     txMd = immuClient.set(key, val);
  9. } catch (CorruptedDataException e) {
  10.     // ...
  11. }
  13. try {
  14.     immuClient.setReferenceAt(refKey, key, txMd.id);
  15. } catch (CorruptedDataException e) {
  16.     // ...
  17. }
  19. try {
  20.     txMd = immuClient.verifiedSetReferenceAt(refKey, key, txMd.id);
  21. } catch (VerificationException e) {
  22.     // ...
  23. }

This feature is not yet supported or not documented. Do you want to make a feature request or help out? Open an issue on Python sdk github projectQueries and history - 图20 (opens new window)

  1. import ImmudbClient from 'immudb-node'
  2. import Parameters from 'immudb-node/types/parameters'
  4. const IMMUDB_HOST = '127.0.0.1'
  5. const IMMUDB_PORT = '3322'
  6. const IMMUDB_USER = 'immudb'
  7. const IMMUDB_PWD = 'immudb'
  9. const cl = new ImmudbClient({ host: IMMUDB_HOST, port: IMMUDB_PORT });
  11. (async () => {
  12.     await cl.login({ user: IMMUDB_USER, password: IMMUDB_PWD })
  14.     const { id } = await cl.set({ key: 'firstKey', value: 'firstValue' })
  15.     await cl.set({ key: 'firstKey', value: 'secondValue' })
  17.     const verifiedSetReferenceAtReq: Parameters.VerifiedSetReferenceAt = {
  18.         key: 'myFirstTag',
  19.         referencedKey: 'firstKey',
  20.         attx: id
  21.     }
  22.     const verifiedSetReferenceAtRes = await cl.verifiedSetReferenceAt(verifiedSetReferenceAtReq)
  23.     console.log('success: verifiedSetReferenceAt', verifiedSetReferenceAtRes)
  25.     const getSecondItemRes = await cl.get({ key: 'myFirstTag' })
  26.     console.log('success: get second item by reference', getSecondItemRes)
  27. })()

This feature is not yet supported or not documented. Do you want to make a feature request or help out? Open an issue on .Net sdk github projectQueries and history - 图21 (opens new window)

If you’re using another development language, please read up on our immugwQueries and history - 图22 (opens new window) option.