Dokumente schreiben - Conare

POST /namespaces/:namespace/documents Schreiben Sie Dokumente in einen Namespace: Conare zerlegt sie in Chunks, bettet sie ein und indexiert sie, und der erste Schreibvorgang legt den Namespace an.

curl https://api.conare.ai/namespaces/docs/documents \
  -H "Authorization: Bearer $CONARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "documents": [
      { "id": "refunds", "text": "Refunds are available for 30 days.", "metadata": { "team": "support" } },
      { "id": "shipping", "text": "Orders ship within two days.", "metadata": { "team": "ops" } }
    ]
  }'

await docs.write([
  { id: "refunds", text: "Refunds are available for 30 days.", metadata: { team: "support" } },
  { id: "shipping", text: "Orders ship within two days.", metadata: { team: "ops" } },
]);

Response

{
  "ids": ["refunds", "shipping"],
  "results": [
    { "id": "refunds", "result": "created", "version": 1, "chunks": 1, "chunks_embedded": 1 },
    { "id": "shipping", "result": "created", "version": 1, "chunks": 1, "chunks_embedded": 1 }
  ],
  "versions": [1, 1]
}

Optionen

Option	Typ	Funktion
`documents`	array, erforderlich	1-100 Dokumente
`id`	string	Bis zu 256 Zeichen aus `A-Z a-z 0-9 . _ : -`; wird ohne Angabe generiert. Das Schreiben einer bestehenden Id ersetzt sie
`text`	string, erforderlich	Beliebig lang innerhalb des 32-MiB-Bodys der Anfrage; ein langer Text bleibt ein Dokument
`metadata`	object	Werte zum Filtern (Regeln)
`user`	string	Wem das Dokument gehört (Nutzer)
`seq`	integer	Ihre Versionsnummer, 0 bis 2^53; ein niedrigeres `seq` als das gespeicherte wird übersprungen
`if_version`	integer	Nur schreiben, wenn die gespeicherte `version` übereinstimmt; `0` schreibt nur ein neues Dokument

Vollständiges Schema: Dokumente hinzufügen.

Antwort

Feld	Bedeutung
`ids`, `versions`	Id und Version jedes Dokuments, in Anfragereihenfolge
`results[].result`	`created`, `updated`, `unchanged` (gleicher Text, gleiche Metadaten und gleicher Nutzer) oder `stale` (ein höheres `seq` ist gespeichert)
`results[].chunks`	Passagen, die das Dokument hat
`results[].chunks_embedded`	Passagen, die dieser Schreibvorgang eingebettet hat; unveränderte werden nicht erneut eingebettet
`results[].stored_seq`	Bei `stale` das gespeicherte `seq`

Eine if_version-Abweichung gibt 409 version_conflict zurück.

Metadaten

{ "team": "support", "year": 2025, "public": true, "tags": ["billing", "refunds"] }

Regel	Limit
Werte	Strings, Zahlen, Booleans oder Arrays von Strings
Schlüssel	Bis zu 32, jeweils 1-64 Zeichen aus `A-Z a-z 0-9 _ . -`, beginnend mit einem Buchstaben
Reservierte Schlüssel	`id`, `text`, `vector`, `ttl_at_ms`
Ein String	Bis zu 4 KiB
Ein Array	Bis zu 256 Strings
Unterschiedliche Werte pro Dokument	Insgesamt 256: Eine Zahl oder ein String bis 222 Bytes zählt zwei; ein Array-Element, ein Boolean oder ein längerer String eins; ein `user` eins, plus eins pro `:`

Nutzer

Setzen Sie user, wenn ein Namespace Dokumente vieler Nutzer enthält, und suchen Sie dann mit user oder user_prefix.

Regel
Format	Bis zu 128 Zeichen aus `A-Z a-z 0-9 . _ : @ -`, beginnend mit einem Buchstaben oder einer Ziffer, höchstens 8 `:`
Gruppen	Schreiben Sie `tenant-7:u_42` und suchen Sie mit `user_prefix: "tenant-7:"` den gesamten Mandanten
Filter	Ein Filter kann nicht auf `user` passen; verwenden Sie `user` und `user_prefix`

Durchsatz

Wenn das Embedding ausgelastet ist, wartet ein Schreibvorgang und gibt Conare-Degraded: embed-busy zurück: Senden Sie weniger Schreibvorgänge gleichzeitig.
Nach etwa 30 Sekunden gibt er 503 mit Retry-After zurück.
Eine fehlgeschlagene Anfrage hat möglicherweise einige Dokumente geschrieben: Wiederholen Sie sie mit demselben Idempotency-Key.