airbyte/docs/integrations/destinations/ragie.md

Ragie

Overview

The Ragie destination connector lets you send data from any Airbyte source into Ragie.ai, a platform for semantic search, vector storage, and AI-powered document retrieval.

This connector transforms your records into documents and ingests them into Ragie’s vector index using its API. It supports advanced options like metadata mapping, document naming, and deduplication via external IDs.

---

Features

• 🔁 Supports append, overwrite, and append + dedup sync modes.
• 🧠 Extracts vector content from specified fields.
• 📎 Attaches custom or static metadata to each document.
• 🏷️ Assigns document names and external IDs.
• 📦 Supports partitioning into multiple datasets (indexes).

---

Prerequisites

• A Ragie.ai account.
• A valid API Key (from the Ragie Dashboard).
• Know your desired data schema and field mappings.

---

Setup Instructions

1. In Airbyte

Go to Destinations → + New Destination → Ragie.

2. Fill in the following fields:

Field	Description	Required
API Key	Your secret Ragie API token.	✅ Yes
Content Fields	List of field(s) from the record to use as the main document content (text). If empty, the whole record is used. Supports dot notation.	⛔ Optional
Metadata Fields	Field(s) to include as metadata. Use dot notation for nested fields.	⛔ Optional
Partition Name	Name of the partition/index in Ragie to write into. Defaults to system partition if empty.	⛔ Optional
Mode	Ingestion mode: 'fast' (default) or 'hi_res'.	✅ Yes
Document Name Field	Field to use as the document’s display name. Auto-generated if empty.	⛔ Optional
Static Metadata (JSON)	JSON string of key-value pairs added to every document’s metadata.	⛔ Optional
External ID Field	Field to use as unique document ID (external_id) for deduplication. Required for append+dedup mode.	⛔ Optional
API URL	URL of Ragie API. Only change if using a private Ragie deployment. Defaults to https://api.ragie.ai.	⛔ Optional

---

Sync Modes

Mode	Behavior
Append	Adds documents to Ragie.
Overwrite	Deletes existing documents in the partition before writing.
Append + Dedup	Uses external_id_field to upsert (insert or update) documents.

---

Example

Incoming Record:

{
  "ticket_id": "1234",
  "description": "The app crashes when I click save.",
  "user": {
    "id": "u_567",
    "email": "alice@example.com"
  }
}

Configuration:

{
  "content_fields": ["description"],
  "metadata_fields": ["user.id", "user.email"],
  "document_name_field": "ticket_id",
  "external_id_field": "ticket_id"
}

Resulting Document in Ragie:

{
  "external_id": "1234",
  "name": "1234",
  "content": "The app crashes when I click save.",
  "metadata": {
    "user.id": "u_567",
    "user.email": "alice@example.com"
  }
}

---

Static Metadata

You can supply additional metadata to all documents by entering a valid JSON string:

Example:

{"source": "airbyte", "env": "prod"}

This will be merged with each document’s metadata.

---

Error Handling

• All fields are validated on connection.
• If invalid content or metadata fields are referenced, errors are logged.
• Connection checks validate API credentials and endpoint reachability.

---

Limitations

• You must supply an external_id_field for deduplication to work.
• Only top-level arrays or objects are currently supported in content fields.
• Ragie currently supports a limited set of ingestion modes (fast, hi_res).

---

Changelog

Version	Changes
0.1.0	Initial release with overwrite/append support and field mapping.

---