Skip to content
Please update to the latest release 0.77.2 to address Multiple CVEs.
VQL Reference
Server
client_set_metadata

client_set_metadata

Function
Arg Description Type
client_id string (required)
metadata A dict containing metadata. If not specified we use kwargs. ordereddict.Dict
modify A modification callback lambda. This performs an atomic mutation on the client metadata.. Lambda
** Free Form Args

Required permissions: COLLECT_CLIENT, SERVER_ADMIN

Description

Sets client metadata.

Client metadata is a set of free form key-value pairs, i.e. a dict.

When updating metadata the result is the same as adding 2 dicts. For existing keys, the value is overwritten.

Setting a metadata key with a NULL value deletes that entry.

Example 

SELECT client_set_metadata(client_id=client_id, metadata=dict(department="Lab02"))
FROM clients()
WHERE os_info.hostname =~ "TRAINING"

Ensuring atomicity

This function is atomic and race free only if the field that is modified does not depend on other client metadata. Generally avoid the get/modify/set pattern as this is not thread safe. It is OK to set a field if you are sure that another artifact will not update the same field at the same time.

If you depend on a previous value in the client metadata you should use the modify callback method. The callback is a lambda which receives the metadata dict under lock and returns a modified dict.

The following example implements a counter.

LET _ <= client_set_metadata(client_id=ClientId,
      modify="x=>x + dict(Foo=int(int=x.Foo || 0) + 1)")

SELECT client_metadata(client_id=ClientId) AS MD
FROM scope()

See also