pkg/api/schema/docs.md
<a name="top"></a>
<a name="schema.proto"></a>
<p align="right"><a href="#top">Top</a></p><a name="immudb.schema.AHTNullableSettings"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| syncThreshold | NullableUint32 | Number of new leaves in the tree between synchronous flush to disk | |
| writeBufferSize | NullableUint32 | Size of the in-memory write buffer |
<a name="immudb.schema.AuthConfig"></a>
DEPRECATED
| Field | Type | Label | Description |
|---|---|---|---|
| kind | uint32 |
<a name="immudb.schema.ChangePasswordRequest"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| user | bytes | Username | |
| oldPassword | bytes | Old password | |
| newPassword | bytes | New password |
<a name="immudb.schema.ChangePermissionRequest"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| action | PermissionAction | Action to perform | |
| username | string | Name of the user to update | |
| database | string | Name of the database | |
| permission | uint32 | Permission to grant / revoke: 1 - read only, 2 - read/write, 254 - admin |
<a name="immudb.schema.ChangeSQLPrivilegesRequest"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| action | PermissionAction | Action to perform | |
| username | string | Name of the user to update | |
| database | string | Name of the database | |
| privileges | string | repeated | SQL privileges: SELECT, CREATE, INSERT, UPDATE, DELETE, DROP, ALTER |
<a name="immudb.schema.ChangeSQLPrivilegesResponse"></a>
<a name="immudb.schema.Chunk"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| content | bytes | ||
| metadata | Chunk.MetadataEntry | repeated |
<a name="immudb.schema.Chunk.MetadataEntry"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| key | string | ||
| value | bytes |
<a name="immudb.schema.Column"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| name | string | Column name | |
| type | string | Column type |
<a name="immudb.schema.CommittedSQLTx"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| header | TxHeader | Transaction header | |
| updatedRows | uint32 | Number of updated rows | |
| lastInsertedPKs | CommittedSQLTx.LastInsertedPKsEntry | repeated | The value of last inserted auto_increment primary key (mapped by table name) |
| firstInsertedPKs | CommittedSQLTx.FirstInsertedPKsEntry | repeated | The value of first inserted auto_increment primary key (mapped by table name) |
<a name="immudb.schema.CommittedSQLTx.FirstInsertedPKsEntry"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| key | string | ||
| value | SQLValue |
<a name="immudb.schema.CommittedSQLTx.LastInsertedPKsEntry"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| key | string | ||
| value | SQLValue |
<a name="immudb.schema.CreateDatabaseRequest"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| name | string | Database name | |
| settings | DatabaseNullableSettings | Database settings | |
| ifNotExists | bool | If set to true, do not fail if the database already exists |
<a name="immudb.schema.CreateDatabaseResponse"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| name | string | Database name | |
| settings | DatabaseNullableSettings | Current database settings | |
| alreadyExisted | bool | Set to true if given database already existed |
<a name="immudb.schema.CreateUserRequest"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| user | bytes | Username | |
| password | bytes | Login password | |
| permission | uint32 | Permission, 1 - read permission, 2 - read+write permission, 254 - admin | |
| database | string | Database name |
<a name="immudb.schema.Database"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| databaseName | string | Name of the database |
<a name="immudb.schema.DatabaseHealthResponse"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| pendingRequests | uint32 | Number of requests currently being executed | |
| lastRequestCompletedAt | int64 | Timestamp at which the last request was completed |
<a name="immudb.schema.DatabaseInfo"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| name | string | Database name | |
| settings | DatabaseNullableSettings | Current database settings | |
| loaded | bool | If true, this database is currently loaded into memory | |
| diskSize | uint64 | database disk size | |
| numTransactions | uint64 | total number of transactions | |
| created_at | uint64 | the time when the db was created | |
| created_by | string | the user who created the database |
<a name="immudb.schema.DatabaseListRequestV2"></a>
<a name="immudb.schema.DatabaseListResponse"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| databases | Database | repeated | Database list |
<a name="immudb.schema.DatabaseListResponseV2"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| databases | DatabaseInfo | repeated | Database list with current database settings |
<a name="immudb.schema.DatabaseNullableSettings"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| replicationSettings | ReplicationNullableSettings | Replication settings | |
| fileSize | NullableUint32 | Max filesize on disk | |
| maxKeyLen | NullableUint32 | Maximum length of keys | |
| maxValueLen | NullableUint32 | Maximum length of values | |
| maxTxEntries | NullableUint32 | Maximum number of entries in a single transaction | |
| excludeCommitTime | NullableBool | If set to true, do not include commit timestamp in transaction headers | |
| maxConcurrency | NullableUint32 | Maximum number of simultaneous commits prepared for write | |
| maxIOConcurrency | NullableUint32 | Maximum number of simultaneous IO writes | |
| txLogCacheSize | NullableUint32 | Size of the cache for transaction logs | |
| vLogMaxOpenedFiles | NullableUint32 | Maximum number of simultaneous value files opened | |
| txLogMaxOpenedFiles | NullableUint32 | Maximum number of simultaneous transaction log files opened | |
| commitLogMaxOpenedFiles | NullableUint32 | Maximum number of simultaneous commit log files opened | |
| indexSettings | IndexNullableSettings | Index settings | |
| writeTxHeaderVersion | NullableUint32 | Version of transaction header to use (limits available features) | |
| autoload | NullableBool | If set to true, automatically load the database when starting immudb (true by default) | |
| readTxPoolSize | NullableUint32 | Size of the pool of read buffers | |
| syncFrequency | NullableMilliseconds | Fsync frequency during commit process | |
| writeBufferSize | NullableUint32 | Size of the in-memory buffer for write operations | |
| ahtSettings | AHTNullableSettings | Settings of Appendable Hash Tree | |
| maxActiveTransactions | NullableUint32 | Maximum number of pre-committed transactions | |
| mvccReadSetLimit | NullableUint32 | Limit the number of read entries per transaction | |
| vLogCacheSize | NullableUint32 | Size of the cache for value logs | |
| truncationSettings | TruncationNullableSettings | Truncation settings | |
| embeddedValues | NullableBool | If set to true, values are stored together with the transaction header (true by default) | |
| preallocFiles | NullableBool | Enable file preallocation |
<a name="immudb.schema.DatabaseSettings"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| databaseName | string | Name of the database | |
| replica | bool | If set to true, this database is replicating another database | |
| primaryDatabase | string | Name of the database to replicate | |
| primaryHost | string | Hostname of the immudb instance with database to replicate | |
| primaryPort | uint32 | Port of the immudb instance with database to replicate | |
| primaryUsername | string | Username of the user with read access of the database to replicate | |
| primaryPassword | string | Password of the user with read access of the database to replicate | |
| fileSize | uint32 | Size of files stored on disk | |
| maxKeyLen | uint32 | Maximum length of keys | |
| maxValueLen | uint32 | Maximum length of values | |
| maxTxEntries | uint32 | Maximum number of entries in a single transaction | |
| excludeCommitTime | bool | If set to true, do not include commit timestamp in transaction headers |
<a name="immudb.schema.DatabaseSettingsRequest"></a>
<a name="immudb.schema.DatabaseSettingsResponse"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| database | string | Database name | |
| settings | DatabaseNullableSettings | Database settings |
<a name="immudb.schema.DebugInfo"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| stack | string | Stack trace when the error was noticed |
<a name="immudb.schema.DeleteDatabaseRequest"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| database | string | Database name |
<a name="immudb.schema.DeleteDatabaseResponse"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| database | string | Database name |
<a name="immudb.schema.DeleteKeysRequest"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| keys | bytes | repeated | List of keys to delete logically |
| sinceTx | uint64 | If 0, wait for index to be up-to-date, If > 0, wait for at least sinceTx transaction to be indexed | |
| noWait | bool | If set to true, do not wait for the indexer to index this operation |
<a name="immudb.schema.DualProof"></a>
DualProof contains inclusion and consistency proofs for dual Merkle-Tree + Linear proofs
| Field | Type | Label | Description |
|---|---|---|---|
| sourceTxHeader | TxHeader | Header of the source (earlier) transaction | |
| targetTxHeader | TxHeader | Header of the target (latter) transaction | |
| inclusionProof | bytes | repeated | Inclusion proof of the source transaction hash in the main Merkle Tree |
| consistencyProof | bytes | repeated | Consistency proof between Merkle Trees in the source and target transactions |
| targetBlTxAlh | bytes | Accumulative hash (Alh) of the last transaction that's part of the target Merkle Tree | |
| lastInclusionProof | bytes | repeated | Inclusion proof of the targetBlTxAlh in the target Merkle Tree |
| linearProof | LinearProof | Linear proof starting from targetBlTxAlh to the final state value | |
| LinearAdvanceProof | LinearAdvanceProof | Proof of consistency between some part of older linear chain and newer Merkle Tree |
<a name="immudb.schema.DualProofV2"></a>
DualProofV2 contains inclusion and consistency proofs
| Field | Type | Label | Description |
|---|---|---|---|
| sourceTxHeader | TxHeader | Header of the source (earlier) transaction | |
| targetTxHeader | TxHeader | Header of the target (latter) transaction | |
| inclusionProof | bytes | repeated | Inclusion proof of the source transaction hash in the main Merkle Tree |
| consistencyProof | bytes | repeated | Consistency proof between Merkle Trees in the source and target transactions |
<a name="immudb.schema.Entries"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| entries | Entry | repeated | List of entries |
<a name="immudb.schema.EntriesSpec"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| kvEntriesSpec | EntryTypeSpec | Specification for parsing KV entries | |
| zEntriesSpec | EntryTypeSpec | Specification for parsing sorted set entries | |
| sqlEntriesSpec | EntryTypeSpec | Specification for parsing SQL entries |
<a name="immudb.schema.Entry"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| tx | uint64 | Transaction id at which the target value was set (i.e. not the reference transaction id) | |
| key | bytes | Key of the target value (i.e. not the reference entry) | |
| value | bytes | Value | |
| referencedBy | Reference | If the request was for a reference, this field will keep information about the reference entry | |
| metadata | KVMetadata | Metadata of the target entry (i.e. not the reference entry) | |
| expired | bool | If set to true, this entry has expired and the value is not retrieved | |
| revision | uint64 | Key's revision, in case of GetAt it will be 0 |
<a name="immudb.schema.EntryCount"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| count | uint64 |
<a name="immudb.schema.EntryTypeSpec"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| action | EntryTypeAction | Action to perform on entries |
<a name="immudb.schema.ErrorInfo"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| code | string | Error code | |
| cause | string | Error Description |
<a name="immudb.schema.ExecAllRequest"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| Operations | Op | repeated | List of operations to perform |
| noWait | bool | If set to true, do not wait for indexing to process this transaction | |
| preconditions | Precondition | repeated | Preconditions to check |
<a name="immudb.schema.Expiration"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| expiresAt | int64 | Entry expiration time (unix timestamp in seconds) |
<a name="immudb.schema.ExportTxRequest"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| tx | uint64 | Id of transaction to export | |
| allowPreCommitted | bool | If set to true, non-committed transactions can be exported | |
| replicaState | ReplicaState | Used on synchronous replication to notify the primary about replica state | |
| skipIntegrityCheck | bool | If set to true, integrity checks are skipped when reading data |
<a name="immudb.schema.FlushIndexRequest"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| cleanupPercentage | float | Percentage of nodes file to cleanup during flush | |
| synced | bool | If true, do a full disk sync after the flush |
<a name="immudb.schema.FlushIndexResponse"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| database | string | Database name |
<a name="immudb.schema.HealthResponse"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| status | bool | If true, server considers itself to be healthy | |
| version | string | The version of the server instance |
<a name="immudb.schema.HistoryRequest"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| key | bytes | Name of the key to query for the history | |
| offset | uint64 | Specify the initial entry to be returned by excluding the initial set of entries | |
| limit | int32 | Maximum number of entries to return | |
| desc | bool | If true, search in descending order | |
| sinceTx | uint64 | If > 0, do not wait for the indexer to index all entries, only require entries up to sinceTx to be indexed |
<a name="immudb.schema.ImmutableState"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| db | string | The db name | |
| txId | uint64 | Id of the most recent transaction | |
| txHash | bytes | State of the most recent transaction | |
| signature | Signature | Signature of the hash | |
| precommittedTxId | uint64 | Id of the most recent precommitted transaction | |
| precommittedTxHash | bytes | State of the most recent precommitted transaction |
<a name="immudb.schema.InclusionProof"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| leaf | int32 | Index of the leaf for which the proof is generated | |
| width | int32 | Width of the tree at the leaf level | |
| terms | bytes | repeated | Proof terms (selected hashes from the tree) |
<a name="immudb.schema.IndexNullableSettings"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| flushThreshold | NullableUint32 | Number of new index entries between disk flushes | |
| syncThreshold | NullableUint32 | Number of new index entries between disk flushes with file sync | |
| cacheSize | NullableUint32 | Size of the Btree node cache in bytes | |
| maxNodeSize | NullableUint32 | Max size of a single Btree node in bytes | |
| maxActiveSnapshots | NullableUint32 | Maximum number of active btree snapshots | |
| renewSnapRootAfter | NullableUint64 | Time in milliseconds between the most recent DB snapshot is automatically renewed | |
| compactionThld | NullableUint32 | Minimum number of updates entries in the btree to allow for full compaction | |
| delayDuringCompaction | NullableUint32 | Additional delay added during indexing when full compaction is in progress | |
| nodesLogMaxOpenedFiles | NullableUint32 | Maximum number of simultaneously opened nodes files | |
| historyLogMaxOpenedFiles | NullableUint32 | Maximum number of simultaneously opened node history files | |
| commitLogMaxOpenedFiles | NullableUint32 | Maximum number of simultaneously opened commit log files | |
| flushBufferSize | NullableUint32 | Size of the in-memory flush buffer (in bytes) | |
| cleanupPercentage | NullableFloat | Percentage of node files cleaned up during each flush | |
| maxBulkSize | NullableUint32 | Maximum number of transactions indexed together | |
| bulkPreparationTimeout | NullableMilliseconds | Maximum time waiting for more transactions to be committed and included into the same bulk |
<a name="immudb.schema.KVMetadata"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| deleted | bool | True if this entry denotes a logical deletion | |
| expiration | Expiration | Entry expiration information | |
| nonIndexable | bool | If set to true, this entry will not be indexed and will only be accessed through GetAt calls |
<a name="immudb.schema.Key"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| key | bytes |
<a name="immudb.schema.KeyListRequest"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| keys | bytes | repeated | List of keys to query for |
| sinceTx | uint64 | If 0, wait for index to be up-to-date, If > 0, wait for at least sinceTx transaction to be indexed |
<a name="immudb.schema.KeyPrefix"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| prefix | bytes |
<a name="immudb.schema.KeyRequest"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| key | bytes | Key to query for | |
| atTx | uint64 | If > 0, query for the value exactly at given transaction | |
| sinceTx | uint64 | If 0 (and noWait=false), wait for the index to be up-to-date, If > 0 (and noWait=false), wait for at lest the sinceTx transaction to be indexed | |
| noWait | bool | If set to true - do not wait for any indexing update considering only the currently indexed state | |
| atRevision | int64 | If > 0, get the nth version of the value, 1 being the first version, 2 being the second and so on If < 0, get the historical nth value of the key, -1 being the previous version, -2 being the one before and so on |
<a name="immudb.schema.KeyValue"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| key | bytes | ||
| value | bytes | ||
| metadata | KVMetadata |
<a name="immudb.schema.LinearAdvanceProof"></a>
LinearAdvanceProof contains the proof of consistency between the consumed part of the older linear chain and the new Merkle Tree
| Field | Type | Label | Description |
|---|---|---|---|
| linearProofTerms | bytes | repeated | terms for the linear chain |
| inclusionProofs | InclusionProof | repeated | inclusion proofs for steps on the linear chain |
<a name="immudb.schema.LinearProof"></a>
LinearProof contains the linear part of the proof (outside the main Merkle Tree)
| Field | Type | Label | Description |
|---|---|---|---|
| sourceTxId | uint64 | Starting transaction of the proof | |
| TargetTxId | uint64 | End transaction of the proof | |
| terms | bytes | repeated | List of terms (inner hashes of transaction entries) |
<a name="immudb.schema.LoadDatabaseRequest"></a>
Database name
| Field | Type | Label | Description |
|---|---|---|---|
| database | string | may add createIfNotExist |
<a name="immudb.schema.LoadDatabaseResponse"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| database | string | Database name |
may add settings |
<a name="immudb.schema.LoginRequest"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| user | bytes | Username | |
| password | bytes | User's password |
<a name="immudb.schema.LoginResponse"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| token | string | Deprecated: use session-based authentication | |
| warning | bytes | Optional: additional warning message sent to the user (e.g. request to change the password) |
<a name="immudb.schema.MTLSConfig"></a>
DEPRECATED
| Field | Type | Label | Description |
|---|---|---|---|
| enabled | bool |
<a name="immudb.schema.NamedParam"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| name | string | Parameter name | |
| value | SQLValue | Parameter value |
<a name="immudb.schema.NewTxRequest"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| mode | TxMode | Transaction mode | |
| snapshotMustIncludeTxID | NullableUint64 | An existing snapshot may be reused as long as it includes the specified transaction If not specified it will include up to the latest precommitted transaction | |
| snapshotRenewalPeriod | NullableMilliseconds | An existing snapshot may be reused as long as it is not older than the specified timeframe | |
| unsafeMVCC | bool | Indexing may not be up to date when doing MVCC |
<a name="immudb.schema.NewTxResponse"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| transactionID | string | Internal transaction ID |
<a name="immudb.schema.NullableBool"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| value | bool |
<a name="immudb.schema.NullableFloat"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| value | float |
<a name="immudb.schema.NullableMilliseconds"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| value | int64 |
<a name="immudb.schema.NullableString"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| value | string |
<a name="immudb.schema.NullableUint32"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| value | uint32 |
<a name="immudb.schema.NullableUint64"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| value | uint64 |
<a name="immudb.schema.Op"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| kv | KeyValue | Modify / add simple KV value | |
| zAdd | ZAddRequest | Modify / add sorted set entry | |
| ref | ReferenceRequest | Modify / add reference |
<a name="immudb.schema.OpenSessionRequest"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| username | bytes | Username | |
| password | bytes | Password | |
| databaseName | string | Database name |
<a name="immudb.schema.OpenSessionResponse"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| sessionID | string | Id of the new session | |
| serverUUID | string | UUID of the server |
<a name="immudb.schema.Permission"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| database | string | Database name | |
| permission | uint32 | Permission, 1 - read permission, 2 - read+write permission, 254 - admin, 255 - sysadmin |
<a name="immudb.schema.Precondition"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| keyMustExist | Precondition.KeyMustExistPrecondition | ||
| keyMustNotExist | Precondition.KeyMustNotExistPrecondition | ||
| keyNotModifiedAfterTX | Precondition.KeyNotModifiedAfterTXPrecondition |
<a name="immudb.schema.Precondition.KeyMustExistPrecondition"></a>
Only succeed if given key exists
| Field | Type | Label | Description |
|---|---|---|---|
| key | bytes | key to check |
<a name="immudb.schema.Precondition.KeyMustNotExistPrecondition"></a>
Only succeed if given key does not exists
| Field | Type | Label | Description |
|---|---|---|---|
| key | bytes | key to check |
<a name="immudb.schema.Precondition.KeyNotModifiedAfterTXPrecondition"></a>
Only succeed if given key was not modified after given transaction
| Field | Type | Label | Description |
|---|---|---|---|
| key | bytes | key to check | |
| txID | uint64 | transaction id to check against |
<a name="immudb.schema.Reference"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| tx | uint64 | Transaction if when the reference key was set | |
| key | bytes | Reference key | |
| atTx | uint64 | At which transaction the key is bound, 0 if reference is not bound and should read the most recent reference | |
| metadata | KVMetadata | Metadata of the reference entry | |
| revision | uint64 | Revision of the reference entry |
<a name="immudb.schema.ReferenceRequest"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| key | bytes | Key for the reference | |
| referencedKey | bytes | Key to be referenced | |
| atTx | uint64 | If boundRef == true, id of transaction to bind with the reference | |
| boundRef | bool | If true, bind the reference to particular transaction, if false, use the most recent value of the key | |
| noWait | bool | If true, do not wait for the indexer to index this write operation | |
| preconditions | Precondition | repeated | Preconditions to be met to perform the write |
<a name="immudb.schema.ReplicaState"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| UUID | string | ||
| committedTxID | uint64 | ||
| committedAlh | bytes | ||
| precommittedTxID | uint64 | ||
| precommittedAlh | bytes |
<a name="immudb.schema.ReplicationNullableSettings"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| replica | NullableBool | If set to true, this database is replicating another database | |
| primaryDatabase | NullableString | Name of the database to replicate | |
| primaryHost | NullableString | Hostname of the immudb instance with database to replicate | |
| primaryPort | NullableUint32 | Port of the immudb instance with database to replicate | |
| primaryUsername | NullableString | Username of the user with read access of the database to replicate | |
| primaryPassword | NullableString | Password of the user with read access of the database to replicate | |
| syncReplication | NullableBool | Enable synchronous replication | |
| syncAcks | NullableUint32 | Number of confirmations from synchronous replicas required to commit a transaction | |
| prefetchTxBufferSize | NullableUint32 | Maximum number of prefetched transactions | |
| replicationCommitConcurrency | NullableUint32 | Number of concurrent replications | |
| allowTxDiscarding | NullableBool | Allow precommitted transactions to be discarded if the replica diverges from the primary | |
| skipIntegrityCheck | NullableBool | Disable integrity check when reading data during replication | |
| waitForIndexing | NullableBool | Wait for indexing to be up to date during replication |
<a name="immudb.schema.RetryInfo"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| retry_delay | int32 | Number of milliseconds after which the request can be retried |
<a name="immudb.schema.Row"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| columns | string | repeated | Column names |
| values | SQLValue | repeated | Column values |
<a name="immudb.schema.SQLEntry"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| tx | uint64 | Id of the transaction when the row was added / modified | |
| key | bytes | Raw key of the row | |
| value | bytes | Raw value of the row | |
| metadata | KVMetadata | Metadata of the raw value |
<a name="immudb.schema.SQLExecRequest"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| sql | string | SQL query | |
| params | NamedParam | repeated | Named query parameters |
| noWait | bool | If true, do not wait for the indexer to index written changes |
<a name="immudb.schema.SQLExecResult"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| txs | CommittedSQLTx | repeated | List of committed transactions as a result of the exec operation |
| ongoingTx | bool | If true, there's an ongoing transaction after exec completes |
<a name="immudb.schema.SQLGetRequest"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| table | string | Table name | |
| pkValues | SQLValue | repeated | Values of the primary key |
| atTx | uint64 | Id of the transaction at which the row was added / modified | |
| sinceTx | uint64 | If > 0, do not wait for the indexer to index all entries, only require entries up to sinceTx to be indexed |
<a name="immudb.schema.SQLPrivilege"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| database | string | Database name | |
| privilege | string | Privilege: SELECT, CREATE, INSERT, UPDATE, DELETE, DROP, ALTER |
<a name="immudb.schema.SQLQueryRequest"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| sql | string | SQL query | |
| params | NamedParam | repeated | Named query parameters |
| reuseSnapshot | bool | Deprecated. If true, reuse previously opened snapshot | |
| acceptStream | bool | Wheter the client accepts a streaming response |
<a name="immudb.schema.SQLQueryResult"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| columns | Column | repeated | Result columns description |
| rows | Row | repeated | Result rows |
<a name="immudb.schema.SQLValue"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| null | google.protobuf.NullValue | ||
| n | int64 | ||
| s | string | ||
| b | bool | ||
| bs | bytes | ||
| ts | int64 | ||
| f | double |
<a name="immudb.schema.ScanRequest"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| seekKey | bytes | If not empty, continue scan at (when inclusiveSeek == true) or after (when inclusiveSeek == false) that key | |
| endKey | bytes | stop at (when inclusiveEnd == true) or before (when inclusiveEnd == false) that key | |
| prefix | bytes | search for entries with this prefix only | |
| desc | bool | If set to true, sort items in descending order | |
| limit | uint64 | maximum number of entries to get, if not specified, the default value is used | |
| sinceTx | uint64 | Controls the visibility lower bound of the scan. - If 0 (default): the server captures the latest committed transaction id at call-reception time and blocks until the indexer has processed at least that transaction before taking the snapshot. This gives "read-latest" / read-your-writes semantics without the caller needing to know the latest tx id (useful when multiple client processes write concurrently, see issue #2082). - If > 0: the server only requires transactions up to sinceTx to be indexed; transactions committed after sinceTx may still be pending and may or may not appear in the result. | |
| noWait | bool | Deprecated and currently ignored by Scan: the server always waits for the tx id resolved from sinceTx (see above) to be indexed before returning. | |
| inclusiveSeek | bool | If set to true, results will include seekKey | |
| inclusiveEnd | bool | If set to true, results will include endKey if needed | |
| offset | uint64 | Specify the initial entry to be returned by excluding the initial set of entries |
<a name="immudb.schema.Score"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| score | double | Entry's score value |
<a name="immudb.schema.ServerInfoRequest"></a>
ServerInfoRequest exists to provide extensibility for rpc ServerInfo.
<a name="immudb.schema.ServerInfoResponse"></a>
ServerInfoResponse contains information about the server instance.
| Field | Type | Label | Description |
|---|---|---|---|
| version | string | The version of the server instance. | |
| startedAt | int64 | Unix timestamp (seconds) indicating when the server process has been started. | |
| numTransactions | int64 | Total number of transactions across all databases. | |
| numDatabases | int32 | Total number of databases present. | |
| databasesDiskSize | int64 | Total disk size used by all databases. |
<a name="immudb.schema.SetActiveUserRequest"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| active | bool | If true, the user is active | |
| username | string | Name of the user to activate / deactivate |
<a name="immudb.schema.SetRequest"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| KVs | KeyValue | repeated | List of KV entries to set |
| noWait | bool | If set to true, do not wait for indexer to index ne entries | |
| preconditions | Precondition | repeated | Preconditions to be met to perform the write |
<a name="immudb.schema.Signature"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| publicKey | bytes | ||
| signature | bytes |
<a name="immudb.schema.Table"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| tableName | string | Table name |
<a name="immudb.schema.TruncateDatabaseRequest"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| database | string | Database name | |
| retentionPeriod | int64 | Retention Period of data |
<a name="immudb.schema.TruncateDatabaseResponse"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| database | string | Database name |
<a name="immudb.schema.TruncationNullableSettings"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| retentionPeriod | NullableMilliseconds | Retention Period for data in the database | |
| truncationFrequency | NullableMilliseconds | Truncation Frequency for the database |
<a name="immudb.schema.Tx"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| header | TxHeader | Transaction header | |
| entries | TxEntry | repeated | Raw entry values |
| kvEntries | Entry | repeated | KV entries in the transaction (parsed) |
| zEntries | ZEntry | repeated | Sorted Set entries in the transaction (parsed) |
<a name="immudb.schema.TxEntry"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| key | bytes | Raw key value (contains 1-byte prefix for kind of the key) | |
| hValue | bytes | Value hash | |
| vLen | int32 | Value length | |
| metadata | KVMetadata | Entry metadata | |
| value | bytes | value, must be ignored when len(value) == 0 and vLen > 0. Otherwise sha256(value) must be equal to hValue. |
<a name="immudb.schema.TxHeader"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| id | uint64 | Transaction ID | |
| prevAlh | bytes | State value (Accumulative Hash - Alh) of the previous transaction | |
| ts | int64 | Unix timestamp of the transaction (in seconds) | |
| nentries | int32 | Number of entries in a transaction | |
| eH | bytes | Entries Hash - cumulative hash of all entries in the transaction | |
| blTxId | uint64 | Binary linking tree transaction ID (ID of last transaction already in the main Merkle Tree) | |
| blRoot | bytes | Binary linking tree root (Root hash of the Merkle Tree) | |
| version | int32 | Header version | |
| metadata | TxMetadata | Transaction metadata |
<a name="immudb.schema.TxList"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| txs | Tx | repeated | List of transactions |
<a name="immudb.schema.TxMetadata"></a>
TxMetadata contains metadata set to whole transaction
| Field | Type | Label | Description |
|---|---|---|---|
| truncatedTxID | uint64 | Entry expiration information | |
| extra | bytes | Extra data |
<a name="immudb.schema.TxRequest"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| tx | uint64 | Transaction id to query for | |
| entriesSpec | EntriesSpec | Specification for parsing entries, if empty, entries are returned in raw form | |
| sinceTx | uint64 | If > 0, do not wait for the indexer to index all entries, only require entries up to sinceTx to be indexed, will affect resolving references | |
| noWait | bool | Deprecated: If set to true, do not wait for the indexer to be up to date | |
| keepReferencesUnresolved | bool | If set to true, do not resolve references (avoid looking up final values if not needed) |
<a name="immudb.schema.TxScanRequest"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| initialTx | uint64 | ID of the transaction where scanning should start | |
| limit | uint32 | Maximum number of transactions to scan, when not specified the default limit is used | |
| desc | bool | If set to true, scan transactions in descending order | |
| entriesSpec | EntriesSpec | Specification of how to parse entries | |
| sinceTx | uint64 | If > 0, do not wait for the indexer to index all entries, only require entries up to sinceTx to be indexed, will affect resolving references | |
| noWait | bool | Deprecated: If set to true, do not wait for the indexer to be up to date |
<a name="immudb.schema.UnloadDatabaseRequest"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| database | string | Database name |
<a name="immudb.schema.UnloadDatabaseResponse"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| database | string | Database name |
<a name="immudb.schema.UpdateDatabaseRequest"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| database | string | Database name | |
| settings | DatabaseNullableSettings | Updated settings |
<a name="immudb.schema.UpdateDatabaseResponse"></a>
Reserved to reply with more advanced response later
| Field | Type | Label | Description |
|---|---|---|---|
| database | string | Database name | |
| settings | DatabaseNullableSettings | Current database settings |
<a name="immudb.schema.UseDatabaseReply"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| token | string | Deprecated: database access token |
<a name="immudb.schema.UseSnapshotRequest"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| sinceTx | uint64 | ||
| asBeforeTx | uint64 |
<a name="immudb.schema.User"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| user | bytes | Username | |
| permissions | Permission | repeated | List of permissions for the user |
| createdby | string | Name of the creator user | |
| createdat | string | Time when the user was created | |
| active | bool | Flag indicating whether the user is active or not | |
| sqlPrivileges | SQLPrivilege | repeated | List of SQL privileges |
<a name="immudb.schema.UserList"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| users | User | repeated | List of users |
<a name="immudb.schema.UserRequest"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| user | bytes | Username |
<a name="immudb.schema.VerifiableEntry"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| entry | Entry | Entry to verify | |
| verifiableTx | VerifiableTx | Transaction to verify | |
| inclusionProof | InclusionProof | Proof for inclusion of the entry within the transaction |
<a name="immudb.schema.VerifiableGetRequest"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| keyRequest | KeyRequest | Key to read | |
| proveSinceTx | uint64 | When generating the proof, generate consistency proof with state from this transaction |
<a name="immudb.schema.VerifiableReferenceRequest"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| referenceRequest | ReferenceRequest | Reference data | |
| proveSinceTx | uint64 | When generating the proof, generate consistency proof with state from this transaction |
<a name="immudb.schema.VerifiableSQLEntry"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| sqlEntry | SQLEntry | Raw row entry data | |
| verifiableTx | VerifiableTx | Verifiable transaction of the row | |
| inclusionProof | InclusionProof | Inclusion proof of the row in the transaction | |
| DatabaseId | uint32 | Internal ID of the database (used to validate raw entry values) | |
| TableId | uint32 | Internal ID of the table (used to validate raw entry values) | |
| PKIDs | uint32 | repeated | Internal IDs of columns for the primary key (used to validate raw entry values) |
| ColNamesById | VerifiableSQLEntry.ColNamesByIdEntry | repeated | Mapping of used column IDs to their names |
| ColIdsByName | VerifiableSQLEntry.ColIdsByNameEntry | repeated | Mapping of column names to their IDS |
| ColTypesById | VerifiableSQLEntry.ColTypesByIdEntry | repeated | Mapping of column IDs to their types |
| ColLenById | VerifiableSQLEntry.ColLenByIdEntry | repeated | Mapping of column IDs to their length constraints |
| MaxColId | uint32 | Variable is used to assign unique ids to new columns as they are created |
<a name="immudb.schema.VerifiableSQLEntry.ColIdsByNameEntry"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| key | string | ||
| value | uint32 |
<a name="immudb.schema.VerifiableSQLEntry.ColLenByIdEntry"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| key | uint32 | ||
| value | int32 |
<a name="immudb.schema.VerifiableSQLEntry.ColNamesByIdEntry"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| key | uint32 | ||
| value | string |
<a name="immudb.schema.VerifiableSQLEntry.ColTypesByIdEntry"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| key | uint32 | ||
| value | string |
<a name="immudb.schema.VerifiableSQLGetRequest"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| sqlGetRequest | SQLGetRequest | Data of row to query | |
| proveSinceTx | uint64 | When generating the proof, generate consistency proof with state from this transaction |
<a name="immudb.schema.VerifiableSetRequest"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| setRequest | SetRequest | Keys to set | |
| proveSinceTx | uint64 | When generating the proof, generate consistency proof with state from this transaction |
<a name="immudb.schema.VerifiableTx"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| tx | Tx | Transaction to verify | |
| dualProof | DualProof | Proof for the transaction | |
| signature | Signature | Signature for the new state value |
<a name="immudb.schema.VerifiableTxRequest"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| tx | uint64 | Transaction ID | |
| proveSinceTx | uint64 | When generating the proof, generate consistency proof with state from this transaction | |
| entriesSpec | EntriesSpec | Specification of how to parse entries | |
| sinceTx | uint64 | If > 0, do not wait for the indexer to index all entries, only require entries up to sinceTx to be indexed, will affect resolving references | |
| noWait | bool | Deprecated: If set to true, do not wait for the indexer to be up to date | |
| keepReferencesUnresolved | bool | If set to true, do not resolve references (avoid looking up final values if not needed) |
<a name="immudb.schema.VerifiableTxV2"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| tx | Tx | Transaction to verify | |
| dualProof | DualProofV2 | Proof for the transaction | |
| signature | Signature | Signature for the new state value |
<a name="immudb.schema.VerifiableZAddRequest"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| zAddRequest | ZAddRequest | Data for new sorted set entry | |
| proveSinceTx | uint64 | When generating the proof, generate consistency proof with state from this transaction |
<a name="immudb.schema.ZAddRequest"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| set | bytes | Name of the sorted set | |
| score | double | Score of the new entry | |
| key | bytes | Referenced key | |
| atTx | uint64 | If boundRef == true, id of the transaction to bind with the reference | |
| boundRef | bool | If true, bind the reference to particular transaction, if false, use the most recent value of the key | |
| noWait | bool | If true, do not wait for the indexer to index this write operation |
<a name="immudb.schema.ZEntries"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| entries | ZEntry | repeated |
<a name="immudb.schema.ZEntry"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| set | bytes | Name of the sorted set | |
| key | bytes | Referenced key | |
| entry | Entry | Referenced entry | |
| score | double | Sorted set element's score | |
| atTx | uint64 | At which transaction the key is bound, 0 if reference is not bound and should read the most recent reference |
<a name="immudb.schema.ZScanRequest"></a>
| Field | Type | Label | Description |
|---|---|---|---|
| set | bytes | Name of the sorted set | |
| seekKey | bytes | Key to continue the search at | |
| seekScore | double | Score of the entry to continue the search at | |
| seekAtTx | uint64 | AtTx of the entry to continue the search at | |
| inclusiveSeek | bool | If true, include the entry given with the seekXXX attributes, if false, skip the entry and start after that one | |
| limit | uint64 | Maximum number of entries to return, if 0, the default limit will be used | |
| desc | bool | If true, scan entries in descending order | |
| minScore | Score | Minimum score of entries to scan | |
| maxScore | Score | Maximum score of entries to scan | |
| sinceTx | uint64 | If > 0, do not wait for the indexer to index all entries, only require entries up to sinceTx to be indexed | |
| noWait | bool | Deprecated: If set to true, do not wait for the indexer to be up to date | |
| offset | uint64 | Specify the index of initial entry to be returned by excluding the initial set of entries (alternative to seekXXX attributes) |
<a name="immudb.schema.EntryTypeAction"></a>
| Name | Number | Description |
|---|---|---|
| EXCLUDE | 0 | Exclude entries from the result |
| ONLY_DIGEST | 1 | Provide keys in raw (unparsed) form and only the digest of the value |
| RAW_VALUE | 2 | Provide keys and values in raw form |
| RESOLVE | 3 | Provide parsed keys and values and resolve values if needed |
<a name="immudb.schema.PermissionAction"></a>
| Name | Number | Description |
|---|---|---|
| GRANT | 0 | Grant permission |
| REVOKE | 1 | Revoke permission |
<a name="immudb.schema.TxMode"></a>
| Name | Number | Description |
|---|---|---|
| ReadOnly | 0 | Read-only transaction |
| WriteOnly | 1 | Write-only transaction |
| ReadWrite | 2 | Read-write transaction |
<a name="immudb.schema.ImmuService"></a>
immudb gRPC & REST service
| .proto Type | Notes | C++ | Java | Python | Go | C# | PHP | Ruby |
|---|---|---|---|---|---|---|---|---|
| <a name="double" /> double | double | double | float | float64 | double | float | Float | |
| <a name="float" /> float | float | float | float | float32 | float | float | Float | |
| <a name="int32" /> int32 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. | int32 | int | int | int32 | int | integer | Bignum or Fixnum (as required) |
| <a name="int64" /> int64 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. | int64 | long | int/long | int64 | long | integer/string | Bignum |
| <a name="uint32" /> uint32 | Uses variable-length encoding. | uint32 | int | int/long | uint32 | uint | integer | Bignum or Fixnum (as required) |
| <a name="uint64" /> uint64 | Uses variable-length encoding. | uint64 | long | int/long | uint64 | ulong | integer/string | Bignum or Fixnum (as required) |
| <a name="sint32" /> sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int | int32 | int | integer | Bignum or Fixnum (as required) |
| <a name="sint64" /> sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long | int64 | long | integer/string | Bignum |
| <a name="fixed32" /> fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int | uint32 | uint | integer | Bignum or Fixnum (as required) |
| <a name="fixed64" /> fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long | uint64 | ulong | integer/string | Bignum |
| <a name="sfixed32" /> sfixed32 | Always four bytes. | int32 | int | int | int32 | int | integer | Bignum or Fixnum (as required) |
| <a name="sfixed64" /> sfixed64 | Always eight bytes. | int64 | long | int/long | int64 | long | integer/string | Bignum |
| <a name="bool" /> bool | bool | boolean | boolean | bool | bool | boolean | TrueClass/FalseClass | |
| <a name="string" /> string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode | string | string | string | String (UTF-8) |
| <a name="bytes" /> bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str | []byte | ByteString | string | String (ASCII-8BIT) |