Метаданные и ссылки
Объект содержит не только байты. Пока invoice-ord_8w2k.pdf — лишь имя и содержимое: для любых сведений warehouse должен прочитать файл целиком. Добавим понятное описание, HTTP-подобные заголовки и произвольные метаданные. Затем изучим ссылки, позволяющие одному объекту представлять другой.
Счета с предыдущих страниц остаются в INVOICES; держите терминал открытым.
Каждый объект имеет ObjectInfo
При put записываются фрагменты, затем итоговые метаданные всего объекта — запись ObjectInfo. Часть полей вычисляется автоматически: размер в байтах, число фрагментов, SHA-256, время изменения и признак удаления. Три поля задаёте вы.
Первое — описание, понятная человеку подпись объекта. Второе — заголовки, пары ключ/значение в формате HTTP, как заголовки сообщения NATS. Третье — метаданные, произвольные строковые пары для нужд приложения.
Задайте их при put. order-svc сохраняет счёт с описанием и заголовком content-type, чтобы читатель узнал о PDF до загрузки байтов:
- CLI
#!/bin/bash
# Put an invoice with metadata attached. Beyond the bytes, every object
# carries an ObjectInfo record. Three of its fields are yours to set:
# --description a human label for the object
# -H / --header HTTP-style headers (repeatable)
# and a free-form metadata map, set in the client libraries.
#
# Here `order-svc` stores invoice-ord_8w2k.pdf with a description and a
# content-type header so a reader knows the bytes are a PDF without
# downloading them first.
nats object put INVOICES invoice-ord_8w2k.pdf \
--description "Invoice for order ord_8w2k" \
--header "content-type:application/pdf"
# The metadata travels in the one metadata message that follows the
# chunks, so it costs nothing extra to read it back later — it is already
# beside the object, not in a separate lookup.
Имя и байты не изменились: это прежний invoice-ord_8w2k.pdf, теперь с описанием и заголовком. Метаданные находятся в том же завершающем сообщении, без отдельной дополнительной записи или операции чтения.
Чтение метаданных
Чтение метаданных не получает байты объекта. Последний ObjectInfo каждого имени хранится одним небольшим сообщением, поэтому warehouse может узнать свойства файла без его загрузки.
- CLI
#!/bin/bash
# Read the ObjectInfo for one object. `nats object info` prints the
# metadata you set (description, headers, metadata map) alongside the
# fields the store computed for you: size, chunk count, the SHA-256
# digest, the modification time, and whether the object is deleted.
#
# `warehouse` reads this before fetching the bytes — the content-type
# header tells it the object is a PDF, and the size tells it how big the
# get will be.
nats object info INVOICES invoice-ord_8w2k.pdf
# Expected output (abridged):
#
# Object information for INVOICES > invoice-ord_8w2k.pdf
#
# Size: 12 KiB
# Modified: 2026-05-22 10:14:22
# Chunks: 1
# Digest: SHA-256=...
# Description: Invoice for order ord_8w2k
# Headers: content-type: application/pdf
В выводе описание и заголовок находятся рядом с вычисленными размером, числом фрагментов, хешем и временем изменения. warehouse читает content-type и размер, затем решает, нужны ли байты. Метаданные служат недорогим указателем содержимого бакета; крупные данные читаются лишь при необходимости.
Метаданные описывают текущий объект, а не историю его версий. Каждый повторный put заменяет их, оставляя последние. История ревизий каждого имени — задача хранилища ключей и значений; хранилище объектов сохраняет текущий ObjectInfo, а не последовательность изменений.
Ссылка направляет один объект на другой
Ссылка — объект, указывающий на другой объект. Get ссылки прозрачно возвращает байты цели: хранилище следует по ссылке. Это ссылка, а не копия: собственных фрагментов у неё нет, сохраняются только бакет и имя цели.
Это полезно, когда два имени должны возвращать одни байты. В Acme этикетка и счёт могут представлять общий документ; стабильное имя может также служить входом к меняющимся файлам. Здесь label-ord_8w2k.png становится ссылкой на счёт, поэтому запрос этикетки возвращает байты счёта:
- CLI
#!/bin/bash
# Add a link from one object to another. A link is an object whose target
# is another object; a get on the link transparently returns the target's
# bytes. Here `label-ord_8w2k.png` is a link that points at the invoice, so
# fetching the label hands back the invoice.
#
# Adding a link is a client-library operation (AddLink / AddBucketLink); the
# `nats` CLI has no link subcommand, so this snippet is illustration only —
# it shows the shape of the call with a client. The store records the target
# {bucket, name} at creation time, then traverses it on get.
#
# Pseudocode:
#
# invoice = os.GetInfo("invoice-ord_8w2k.pdf")
# os.AddLink("label-ord_8w2k.png", invoice)
#
# Once the link exists, a client get on the link name returns the invoice
# bytes, traversed for you:
#
# os.Get("label-ord_8w2k.png") # returns the invoice's bytes
# A bucket link points at a whole bucket instead of one object: pass an
# empty target name. It stores only a reference to the other bucket, so a
# get on a bucket link returns an error (ErrCantGetBucket in Go), not bytes.
# Read the link's info to learn the target bucket, then open that bucket
# yourself. Reach for a bucket link when you want a stored pointer to
# another store, not a gettable object.
Ссылка может указывать на целый бакет. Это ссылка на бакет: имя цели пустое, сохраняется только другой бакет. Get такой ссылки не возвращает байты, а завершается ошибкой (ErrCantGetBucket в Go). Прочитайте сведения ссылки, узнайте целевой бакет и откройте его самостоятельно. Это сохранённый указатель на хранилище, а не доступный через get объект.
Хранилище соблюдает два ограничения: нельзя ссылаться на удалённый объект или на другую ссылку. Цепочки ссылок не создаются. При добавлении записывается текущая цель, а каждый последующий get разрешает её.
Все поля ObjectInfo и параметры ссылок приведены в справочнике. Здесь достаточно поведения.
Подводные камни
Здесь две ловушки: изменение цели ссылки и границы действия UpdateMeta.
Ссылка фиксирует адрес при создании и не отслеживает его изменения. Она сохраняет бакет и имя, но не поддерживает существование цели. После удаления цели ссылка остаётся висячей: get возвращает ErrObjectNotFound. Переименование ломает её так же, поскольку сохранено старое имя. Не считайте, что addLink удерживает цель или следует за переименованием. Перед использованием проверяйте её через info; после удаления или переименования создавайте ссылку заново.
Вот ошибка и безопасная проверка рядом: удалите счёт, запросите устаревшую ссылку этикетки, проверьте цель через info, затем снова запишите счёт, чтобы ссылка разрешалась, а бакет вернулся в прежнее состояние:
- CLI
#!/bin/bash
# A link is a snapshot of its target at creation time, not a live
# reference that keeps the target alive. Delete the target and the link
# is left dangling: a get on the link fails with a not-found error.
#
# Delete the invoice that label-ord_8w2k.png points at:
nats object rm INVOICES invoice-ord_8w2k.pdf --force
# Now get the link. The store traverses to invoice-ord_8w2k.pdf, finds it
# deleted, and fails — the link still exists, but its target does not:
#
# nats: error: nats: object not found
#
# In a client library this surfaces as ErrObjectNotFound. Always confirm
# the target exists before depending on a link, and re-create the link
# after you delete or rename its target.
nats object get INVOICES label-ord_8w2k.png
# Confirm the target before you depend on the link. `nats object info`
# returns the metadata if the target is present and the same not-found
# error if it is gone:
nats object info INVOICES invoice-ord_8w2k.pdf
# Restore the running example. Re-put the invoice with its description and
# content-type header so the bucket is back to where the chapter left it
# and the label link resolves again:
nats object put INVOICES invoice-ord_8w2k.pdf --force \
--description "Invoice for order ord_8w2k" \
--header "content-type:application/pdf"
UpdateMeta меняет имя, описание, заголовки и метаданные, но не размер фрагмента или цель ссылки. Изменение имени переименовывает объект. Переданные новые размер фрагмента или цель ссылки молча отбрасываются: вызов успешен, но поля не сохраняются. Размер фиксируется при записи байтов, цель — при создании ссылки. Для изменения размера удалите объект и выполните put заново; для изменения цели удалите ссылку и добавьте новую. Переименование в существующее неудалённое имя возвращает ErrObjectAlreadyExists. В удалённое имя переименовать можно, заняв его снова.
Текущее состояние
Теперь у вас есть:
invoice-ord_8w2k.pdfс описанием и заголовкомcontent-type, доступными без чтения байтов.label-ord_8w2k.pngкак ссылка на счёт с прозрачным разрешением при get.- Понимание ограничений ссылок — без удалённой цели и без ссылки на ссылку — и полей, изменяемых
UpdateMeta.
В бакете есть объект с метаданными и ссылка рядом с ним. Следующая страница переходит к бакету целиком: снимку содержимого и наблюдению за изменениями.
Что дальше
Изучим list и watch: снимок всех объектов и поток метаданных, через который analytics наблюдает за заполнением бакета.
Переходите к странице Наблюдение и список объектов.
См. также
- Ключи и значения — история ревизий каждого ключа вместо только последнего объекта.
- Справочник — все поля
ObjectInfoи параметры ссылок.