Skip to main content
Version: Next

Attachments ($meta)

You can store attachments for any entry by writing records into a dedicated system entry:

<parent_entry_name>/$meta

This is useful for schema fragments, calibration metadata, plugin configuration, or any small JSON payload that should travel with the entry.

Attachments are regular records with a few extra rules. Each attachment is identified by a required key label, which lets you store multiple attachments in the same $meta entry and update/remove them individually.

For example, if your parent entry name is robot/front/camera, the attachments entry is robot/front/camera/$meta.

Reserved Keys

Attachment keys starting with $ are reserved for internal ReductStore purposes. Please use keys without a leading $ for user-defined attachments.

Create or Replace an Attachment​

Write the attachment content as a normal record body and set the attachment key label.

If a record with the same key already exists in the same $meta entry, ReductStore replaces it automatically.

For write requests:

  • x-reduct-label-key is required.
  • Writing with the same key replaces the previous attachment with that key.
  • Writing with x-reduct-label-remove: true is not allowed. Use a label update (PATCH) to remove an attachment.

Attachments can also be created with batch endpoints. The same rules apply: the entry path must end with /$meta, and the key label is required for each attachment record.

Changes:

  • Version 1.19: Entry attachments in system $meta entries were introduced.
  • Version 1.19: entry names can be hierarchical paths with multiple segments (for example, a/b/c).
POST
/api/v1/b/:bucket_name/:entry_name/$meta
Write an attachment record

If a $meta record with key=$plugin already exists, it is replaced by this new record.

Read an Attachment​

Reading attachments works exactly like reading regular records: use the attachment path and timestamp.

Because $meta is a system entry:

  • It is hidden from bucket entry_count and entry lists.
  • Wildcard entry-name queries do not include it, so you must address it by its exact path (<parent_entry_name>/$meta).

If you don't know the timestamp of an attachment, query the $meta entry by key first (see the Query API).

GET
/api/v1/b/:bucket_name/:entry_name/$meta
Read an attachment record

Remove an Attachment​

To remove an attachment, update labels of the existing $meta record and set remove=true.

This is intentionally done through PATCH (update), not through a write request. It is also the recommended way when replication is enabled, because record deletions are not replicated.

The PATCH request must target an existing attachment record timestamp.

PATCH
/api/v1/b/:bucket_name/:entry_name/$meta
Remove attachment by key (`remove=true`)

Delete $meta Entry Directly​

Direct deletion of the system $meta entry is not allowed.

If you need to delete it, remove the parent entry instead. The $meta entry is removed together with its parent.

$meta records are included in bucket size/usage accounting, and $meta is renamed automatically when its parent entry is renamed.

DELETE
/api/v1/b/:bucket_name/:entry_name/$meta
Remove a `$meta` entry directly (forbidden)

Typical Flow​

In practice, attachment handling usually looks like this:

  1. Write attachment data to <parent_entry_name>/$meta with a key.
  2. Write a newer record with the same key when you need to update it.
  3. Query <parent_entry_name>/$meta by key if you need to find the attachment timestamp.
  4. Read the attachment record when needed.
  5. Remove it with PATCH and x-reduct-label-remove: true.