Preview AI relationship discovery
Analyzes the datasets in your template and uses AI to suggest how
they relate to each other -- for example, that orders.customer_id
likely references customers.id. This is a preview-only operation;
nothing is saved.
Send a template containing at least two datasets. The AI inspects
field names, types, and naming conventions to suggest how your tables
relate to each other. The response includes both the raw suggestions
and a candidateTemplate with those relationships already merged in,
ready to save or edit via
PUT /api/v1/domains/{domainId}/template.
Discovery is skipped when:
- The template has fewer than 2 datasets (nothing to relate).
- The template already has active relationships (to avoid overwriting your existing joins).
When skipped, skipped is true and skippedReason explains why.
When discovery runs, any existing inactive relationships are
preserved. New AI-discovered relationships are appended with
discoveredBy: "ai" and isActive: true. The confidence and
joinPriority fields reflect how certain the AI is about each
suggestion.
Authorization
BearerAuth A project-scoped access token. Generate one via the Token API with your projectId and projectSecret.
In: header
Path Parameters
The unique identifier of the semantic domain.
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X post "https://semaphor.cloud/api/v1/domains/domain_abc123/template/discovery" \ -H "Content-Type: application/json" \ -d '{ "template": {} }'{
"suggestions": [
{
"sourceDataset": "orders",
"sourceFields": [
"customer_id"
],
"targetDataset": "customers",
"targetFields": [
"id"
],
"cardinality": "many_to_one",
"defaultJoinType": "LEFT",
"confidence": "high",
"rationale": "orders.customer_id likely references customers.id"
}
],
"candidateTemplate": {
"schemaVersion": "2.0",
"id": "domain_abc123",
"name": "sales_metrics",
"label": "Sales Metrics",
"description": "Revenue and order tracking",
"datasets": [
{
"name": "orders",
"label": "Orders",
"type": "physical",
"connectionId": "conn_1",
"connectionType": "PostgreSQL",
"catalog": "string",
"schema": "public",
"table": "orders",
"sql": "string",
"primaryKey": [
"order_id"
],
"fields": {
"identifiers": [
{}
],
"dimensions": [
{}
],
"metrics": [
{}
]
}
}
],
"relationships": [
{
"id": "string",
"name": "orders_to_customers",
"sourceDataset": "orders",
"sourceFields": [
"customer_id"
],
"targetDataset": "customers",
"targetFields": [
"id"
],
"cardinality": "many_to_one",
"defaultJoinType": "LEFT",
"isAutoJoin": true,
"joinPriority": 10,
"discoveredBy": "ai",
"confidence": "high",
"isActive": true,
"description": "string"
}
],
"calculatedMetrics": {},
"calculatedDimensions": {},
"grainMappings": [
{}
]
},
"skipped": true,
"skippedReason": "insufficient_datasets",
"warnings": [
{
"code": "SCHEMA",
"message": "Template schema error at datasets.0.name: Required",
"severity": "error",
"hint": "Update the domain template shape to match the semantic schema.",
"context": {}
}
]
}{
"error": "string",
"details": {},
"errors": [
{
"code": "SCHEMA",
"message": "Template schema error at datasets.0.name: Required",
"severity": "error",
"hint": "Update the domain template shape to match the semantic schema.",
"context": {}
}
],
"warnings": [
{
"code": "SCHEMA",
"message": "Template schema error at datasets.0.name: Required",
"severity": "error",
"hint": "Update the domain template shape to match the semantic schema.",
"context": {}
}
]
}{
"error": "string",
"details": {},
"errors": [
{
"code": "SCHEMA",
"message": "Template schema error at datasets.0.name: Required",
"severity": "error",
"hint": "Update the domain template shape to match the semantic schema.",
"context": {}
}
],
"warnings": [
{
"code": "SCHEMA",
"message": "Template schema error at datasets.0.name: Required",
"severity": "error",
"hint": "Update the domain template shape to match the semantic schema.",
"context": {}
}
]
}{
"error": "string",
"details": {},
"errors": [
{
"code": "SCHEMA",
"message": "Template schema error at datasets.0.name: Required",
"severity": "error",
"hint": "Update the domain template shape to match the semantic schema.",
"context": {}
}
],
"warnings": [
{
"code": "SCHEMA",
"message": "Template schema error at datasets.0.name: Required",
"severity": "error",
"hint": "Update the domain template shape to match the semantic schema.",
"context": {}
}
]
}{
"error": "string",
"details": {},
"errors": [
{
"code": "SCHEMA",
"message": "Template schema error at datasets.0.name: Required",
"severity": "error",
"hint": "Update the domain template shape to match the semantic schema.",
"context": {}
}
],
"warnings": [
{
"code": "SCHEMA",
"message": "Template schema error at datasets.0.name: Required",
"severity": "error",
"hint": "Update the domain template shape to match the semantic schema.",
"context": {}
}
]
}{
"error": "string",
"details": {},
"errors": [
{
"code": "SCHEMA",
"message": "Template schema error at datasets.0.name: Required",
"severity": "error",
"hint": "Update the domain template shape to match the semantic schema.",
"context": {}
}
],
"warnings": [
{
"code": "SCHEMA",
"message": "Template schema error at datasets.0.name: Required",
"severity": "error",
"hint": "Update the domain template shape to match the semantic schema.",
"context": {}
}
]
}