POST /compose/links/ingest

Stores explicit value mappings between a source field and a target field in a named link collection. Used to define cross-encoding joins where fields have different types or structures. Each call replaces all existing links for the given collection.

---

Request

Content-Type: application/json

Body:

Parameter	Type	Required	Description
link_collection	string	✅	Name of the link collection to create or replace
source_collection	string	✅	Name of the source data collection
source_field	string	✅	Field name in the source collection
target_collection	string	✅	Name of the target data collection
target_field	string	✅	Field name in the target collection
links	list of objects	✅	List of value mappings. Each entry: {"source_value": ..., "target_value": ..., "weight": ...}

Link object:

Field	Type	Required	Description
source_value	string	✅	Value from the source field
target_value	string	✅	Corresponding value in the target field
weight	float	❌	Optional weight for the link (stored but not currently used in matching)

---

Behavior

Both forward (source → target) and reverse (target → source) mappings are built and stored in memory. Any existing links for link_collection are completely replaced on each call. Links with missing source_value or target_value are silently skipped.

---

Responses

200 OK

{
  "status": "success",
  "links_created": 42,
  "link_collection": "expertise_to_employees"
}

Field	Description
links_created	Total number of link entries processed
link_collection	Name of the collection that was created or replaced

Error Responses

Status	Condition
500	Unexpected internal error

---

Notes

• Link storage is currently in-memory and will not persist across server restarts.
• Each call fully replaces the existing link collection — there is no partial update.
• Use /compose/links/match to query stored links, and /compose/links/{link_collection} to inspect them.

---

Example

import requests

SERVER_URL = "http://18.220.128.24:8000"
API_KEY    = "yourapitoken"

def ingest_links(link_collection: str, links: list) -> dict:
    response = requests.post(
        f"{SERVER_URL}/compose/links/ingest",
        headers={"X-API-Key": API_KEY},
        json={
            "link_collection":  link_collection,
            "source_collection": "expertise",
            "source_field":      "subject",
            "target_collection": "employees",
            "target_field":      "name",
            "links":             links,
        },
    )
    response.raise_for_status()
    return response.json()


result = ingest_links(
    link_collection="expertise_to_employees",
    links=[
        {"source_value": "machine learning", "target_value": "Alice"},
        {"source_value": "machine learning", "target_value": "Bob"},
        {"source_value": "finance",          "target_value": "Carol"},
    ],
)
print(result)

Expected output:

{
  "status": "success",
  "links_created": 3,
  "link_collection": "expertise_to_employees"
}