25. Key/value lookups#

In addition to timeseries operations, QuasarDB also provides a key/value database under the hood. This chapter shows some examples on how to interact with key/value records directly.

25.1. PUT#

PUT creates a scalar key/value entry. It does not replace an existing entry. The command returns an error if the key already exists.

PUT stores the entry without an expiration time.

PUT <scalar_type> <key> <value>

scalar_type ::= BLOB | DOUBLE | INT | INT64 | INTEGER | STRING | TIMESTAMP

scalar_type: The data type of the entry. INT and INTEGER are aliases for INT64.
key: The name of the entry. Use double quotation marks around a name that contains special characters.
value: The value to store. The value must be compatible with scalar_type. Put BLOB and STRING values in single quotation marks.

Create a blob entry:

PUT BLOB "sensor/config" 'sample every 10 seconds'

Create a 64-bit integer entry:

PUT INT64 "sensor/count" 42

Create a timestamp entry:

PUT TIMESTAMP "sensor/installed_at" 2026-01-15T10:30:00Z

To change an existing key/value entry, use the applicable client API.

25.2. FIND#

FIND selects entries by tag, name, or type. Other query commands can use a FIND expression instead of an explicit entry name.

FIND (
  {
    TAG = <tag_value>
    | NOT TAG = <tag_value>
    | PREFIX = '<prefix>'
    | SUFFIX = '<suffix>'
    | TYPE = <entry_type>
  }
  [ AND ... ]
  [ , RECURSIVE = { TRUE | FALSE } ]
)

tag_value ::= { '<text>' | $table } [ || ... ]

entry_type ::= {
  BLOB | DOUBLE | INT | INT64 | INTEGER | STRING | TIMESTAMP |
  DEQUE | HSET | STREAM | TAG | TS
}

TAG: Selects entries that have the specified tag. Add NOT to exclude entries that have the tag.
PREFIX: Selects entries whose names start with the specified text.
SUFFIX: Selects entries whose names end with the specified text.
TYPE: Selects entries of the specified type.
RECURSIVE: Also searches through tags that match the expression. The default value is FALSE.
$table: Uses the current table name in a tag expression. Use || to join the table name and text.

25.3. Examples#

Find all key/value entries that have the tag “stocks”:

FIND(tag='stocks')

Find all timeseries that have the tag “stocks”:

FIND(tag='stocks' AND type=ts)

Find all entries that have the tags “stocks”, “euro”, “industry”:

FIND(tag='stocks' AND tag='euro' AND tag='industry')

Find all entries that have the tags “stocks”, “euro”, “industry” but not “germany”:

FIND(tag='stocks' AND tag='euro' AND tag='industry' AND NOT tag='germany')

Find all entries that have the tags “stocks”, “euro”, “industry” but not “germany”, and are a time series:

FIND(tag='stocks' AND tag='euro' AND tag='industry' AND NOT tag='germany' AND type=ts)

Find all entries that have the tag “stocks”, then for each tag <Y> found add the results from FIND(tag='<Y>', RECURSIVE=TRUE):

FIND(tag='stocks', RECURSIVE=TRUE)

Find all entries whose names start with market/:

FIND(PREFIX='market/')

Find all entries whose names end with /trades:

FIND(SUFFIX='/trades')

Find all string entries:

FIND(TYPE=STRING)

Find tables whose tag contains the table name:

FIND(TAG='source/' || $table)

To add, remove, or list tags, refer to tag commands.