Which file formats and fields does a reference source accept, and how do I add more documents later?

Tares accepts json, csv, md and txt documents in a reference source. Each attachment needs a name and content, and can carry an optional format and labels. To add documents later, re-open the source and choose Upload more. Editing the source re-materializes it, so it has no poll interval and no entity key.

How it works

A reference source holds declarative reference material, such as project notes, schemas and runbooks. It is not a stream of events. The config is the data: each attachment carries its own labels and content, and Tares turns each document into one always-surfaced event.

• Formats: json, csv, md and txt. Tares reads uploaded files into text.
• Required fields per attachment: name (the file name or title) and content (the document’s text).
• Optional fields per attachment: format (one of the four formats above) and labels (the entity labels, for example service set to tares).
• Source-level labels: the labels list declares the label names so reads can correlate on them. Each attachment provides the values.

The labels you tag each document with become real Tares labels. You can read them and trigger on them.

Because documents attach to an entity by its labels, Tares always surfaces them when it correlates on that entity. The read time window does not apply, so a runbook does not age out of a 15-minute read.

Editing the source re-materializes it. That is why a reference source has no poll interval and no entity key. Correlation is label-native.

The reference connector page covers the full field list.

Set it up

1. Open Sources, choose Add source, then pick Reference documents.
2. Upload your json, csv, md or txt files. Tares reads each file into text.
3. Tag each document with the labels of the entity it describes, for example service=tares and environment=production.
4. Choose Create.
5. To add more documents later, re-open the source and choose Upload more.

You can also declare the source in YAML. Send the same object with POST /api/sources.

- name: runbooks
  connector: reference
  config:
    attachments:
      - name: restart.md
        format: md
        content: |
          1. kubectl rollout restart deploy/tares
          2. watch the pod come healthy
        labels: { service: tares, environment: production }
    labels:
      - { name: service, field: service }
      - { name: environment, field: environment }

To add a document through config, add another entry under attachments with its own name, content and labels.

To verify, open the source. Recent events shows one event per document, and Fields shows the labels they carry. Then read the entity the documents describe:

read({ service: tares })

The documents come back in the timeline, even outside the read window.

What you get

• One always-surfaced event per document, with the labels you set on it.
• Runbooks, schemas and notes that appear whenever Tares correlates on the entity they describe, whatever the read window.
• Labels you can read and trigger on, like labels from any other source.
• A source you extend any time with Upload more, or by editing the config, with no poll interval to manage and no entity key to define.

When something else fits

• If you need a continuous stream of events that age out of the read window, use an event connector instead, such as the webhook, polled or OTLP connectors.
• If your documents live on a system that changes often and you want Tares to pull them on a schedule, the http_poll connector reads a JSON endpoint on an interval.

Related