Optional technical reference. This material is for developers, integration specialists and platform administrators. For the consultant lesson, read the practical guide.
Preserved from source baseline
d4587c7c0e073e58c2d430342f65ac55dd701bf4; source/static examples retain their stated scope. They are not new runtime verification or required consultant setup steps.
Fabric
Learn the catalog, plan and record boundaries
Fabric describes sources, logical entities, datasets and relationships. Treat these as separate stages: catalog discovery explains available metadata; resolution produces an admitted plan; materialization executes that plan; record reads apply the current dataset policy. A source name or visible catalog entry alone does not authorize all rows, another workspace's contract, or disclosure to a model.
| Your question | Surface | Important distinction |
|---|---|---|
| What data products exist for me? | datasets/entities/relationships catalog | Results are filtered through current access. |
| What would this parameterized dataset use? | dataset resolve | A plan is not materialized data. |
| Can I build or refresh the result? | materialize | A separately authorized mutation with an original intent. |
| What records may I read now? | materialized-records | Current mask/deny and contract policy still applies. |
Use only admitted synthetic datasets in the following exercises. Replace dataset IDs, run IDs and paging cursors with actual returned coordinates. The examples explain source contracts; no connector/database or AI provider was called for this manual.
Example UIAI-AI_FABRIC-01 — Discover a dataset and read its readiness
Scenario and inputs. Nadia wants a demonstration overview of five requested leave days in people-ops. A data steward has already admitted a suitable synthetic dataset; its actual ID must come from the catalog. Human data access and AI-disclosure approval are separate prerequisites.
Procedure. Read /api/ai-fabric/datasets, select an authorized entry, then inspect its detail and /api/ai-fabric/readiness. Follow its logical entity/source/relationship references to understand the intended shape. Retain the actual dataset ID and explain which fields are needed for the summary; do not substitute a display label into later routes. If inspecting a separate Studio Fabric under /api/fabrics, follow its source-visibility and redacted-binding rules below rather than applying XML catalog response assumptions.
Expected result. The reader understands the dataset's metadata and readiness gaps. Catalog operations do not materialize rows or prove that a connector will succeed. A visible dataset can still require a different permission for resolve or materialize, and a cross-workspace mapping retains its explicit contract gate.
Failure and recovery. Missing or denied entries are not zero business rows. Ask the data owner to inspect the admitted catalog or grant; do not query raw underlying storage to bypass a filtered listing. A readiness failure should lead to its specific source/connection/configuration remedy, not invented sample rows that look like live data.
Sources. Filtered catalog and readiness, dataset access checks, distinct Studio Fabric read shaping, hidden binding projection.
Example UIAI-AI_FABRIC-02 — Resolve parameters before materialization
Scenario and inputs. The dataset's owner documents a supported parameter named employeeId. Nadia has the actual synthetic employee ID and AI_FABRIC_QUERY plus the dataset's current object/contract access. An arbitrary parameter name is not assumed to be accepted by every dataset.
Procedure. Call POST /api/ai-fabric/datasets/{datasetId}/resolve using its real identifier and the parameters wrapper below, replacing the employee value. parameters is a serialized VariableMap: business parameter names belong inside its values member. This differs from endpoints whose DTO explicitly accepts a flat map; the Fabric controller does not call the flat-map compatibility helper. Inspect the returned plan's declared source/query/projection rather than treating it as a row collection. Review any cross-workspace mapping before deciding whether to execute it.
{"parameters":{"values":{"employeeId":"REPLACE_WITH_SYNTHETIC_EMPLOYEE_ID"}}}
Expected result. Resolution delegates to the actual dataset query service after artifact, contract and policy checks. It supplies an admitted plan for those parameters; it does not by itself create a materialization run, approve an AI prompt or imply write permission on a target table.
Failure and recovery. A refused parameter, stale dataset contract or inaccessible source must be corrected through its owner. Do not remove contract checks or replace the dataset with an arbitrary connector query. If the dataset has different declared parameters, use that actual declaration; the example wrapper is complete JSON but its business parameter is fixture-specific.
Sources. Resolve route, request wrapper.
Example UIAI-AI_FABRIC-03 — Materialize one deliberate intent and inspect records
Scenario and inputs. An authorized data operator has reviewed the synthetic dataset plan and may materialize it. They retained the exact dataset ID, accepted parameters and an original operation intent. This is separate from Nadia's catalog-view permission and may contact the admitted data source.
Procedure. Submit the actual materialization fields to /api/ai-fabric/datasets/{datasetId}/materialize. Keep the original idempotencyKey for this intent, choose forceRefresh deliberately, and retain returned run coordinates. Read the authorized result through the dataset's materialized-records route, not through a direct database or an assumed unguarded run URL.
{
"parameters":{"values":{"employeeId":"REPLACE_WITH_SYNTHETIC_EMPLOYEE_ID"}},
"forceRefresh":false,
"idempotencyKey":"leave-demo-materialize-014",
"options":{}
}
Expected result. The mutation enters its native artifact/contract/policy checks. Record reads still enforce current READ_RECORDS policy, including field masking where prescribed. A materialization receipt describes this operation, not permanent disclosure approval or guaranteed freshness for every later consumer.
Failure and recovery. After an uncertain reply, reconcile the original operation through its documented service receipt before minting a new intent or force-refreshing again. A denied materialization cannot be repaired by borrowing a privileged identity. These source-reviewed request shapes are not evidence that a database run was performed for the documentation.
Sources. Materialize and record routes, actual mutation DTO.
Example UIAI-AI_FABRIC-04 — Page governed records and handle a relationship refusal
Scenario and inputs. The operator has a known admitted dataset and a returned record key from its first read. Another exercise follows one of that dataset's relationships into a separate workspace. Neither the cursor nor a relationship ID grants access by itself.
Procedure. Read the dataset records with a small limit, then use the actual last record key as after for the next keyset page. Keep the same dataset and current authorized context. For relationship resolution, supply the documented relationship input as {"leftSide":{"values":{"customerNumber":"C-100"}}} to its resolve route, replacing the fixture-specific member with the admitted declaration and review the governing dataset's contract access. Inspect masked fields as masked values rather than joining around them.
Expected result. The records route bounds output and applies current dataset policy. Relationship resolution checks both AI_FABRIC_QUERY and its governing cross-workspace dataset contract; a generic query permission alone is insufficient. A successful authorized empty page differs from a failed/refused request.
Failure and recovery. If the next dataset/page or relationship is unavailable, retain that result as unavailable rather than showing a false total of zero. Ask the dataset/contract owner to resolve the actual missing admission. Do not substitute a raw storage query, alter the cursor to another dataset, or disclose fields that the effective policy masked.
Sources. Keyset record read and masking, relationship contract gate, security tests.
This manual describes the XML AiFabric catalog, query-plan and materialization
services under /api/ai-fabric. Studio also has a distinct workspace Fabric
designer at /workspaces/:workspaceKey/fabric, with drafts/publication under
/api/fabrics. Published Studio fabrics can be selected in the
Query Builder and supported interface data paths. Do not
interpret the catalog planning-layer limitations below as absence of that
designer, or treat a plan as proof that an external source has executed.
Studio Fabric: a blank source can be a protected existing binding
For workspace Studio Fabric reads under /api/fabrics, permission to view the Fabric does not imply permission to view every bound connector. When a source is hidden, draft/version reads and publish responses blank both binding.connectorId and binding.objectRef (the table/object reference). A type description that names either protected value is cleared. Binding kind, fields and the API resource pin remain; this is a specific projection rule, not a guarantee that every source-related string anywhere in arbitrary metadata is removed.
Treat that blank pair as a potentially redacted existing source, not proof that the type is unbound or the stored table was deleted. When saving unrelated edits, preserve the returned type key, binding kind and remaining binding properties. The secured service restores the stored connector/table for the same type key and kind before checking visibility. A genuinely unchanged binding can survive the save; changing its hidden binding properties still needs visibility and is refused when the source is unavailable. This does not grant permission to guess a connector/table or replace hidden source configuration. A conflict still needs the actual supported revision recovery.
Publication also retains source checks: an unchanged binding is compared with the latest published version, whereas a first or changed hidden binding is refused. The publish response is redacted for the caller, but replication setup receives the stored published source. A blank response therefore does not disable replication or authorize source reads. Preview/source-visibility and row access keep their independent gates. Report unavailable source information neutrally and refer binding changes to an operator who actually has the required access; do not copy protected source details into chat or a model prompt.
Sources: read/publish response projection, exact redaction/restoration scope, save and publication checks, stored-source replication handoff, save-of-redacted-read fixture, first/unchanged publication fixtures.
Fabric is the platform layer for governed relationships across databases, APIs, connectors, files, workflow outputs, event streams, and AI-enriched datasets.
It is not limited to foreign keys inside one database. It models business entities and relationships across systems.
flowchart TD
A["Physical Sources"] --> B["Physical Objects"]
B --> C["Logical Entities"]
C --> D["Semantic Relationships"]
D --> E["Datasets"]
E --> F["Reports"]
E --> G["Workflow Decisions"]
E --> H["AI Agents"]
Fabric definitions can be loaded from XML under:
conf/ai-fabric/
Core Concepts
AiFabricSource: database, API, connector, file, event stream, workflow output, or AI-enriched dataset source.AiFabricObject: physical table, API resource, file schema, event topic, or materialized dataset.LogicalEntity: business object such as Customer, Invoice, Employee, Case, Vendor, or Claim.SemanticRelationship: relationship between logical entities using strategies such as API lookup, cross-database join, connector lookup, materialized relationship, or AI-assisted match.DatasetDefinition: reusable dataset assembled from entities and relationships.
First Implementation
The first implementation provides Java contracts, an XML catalog loader, startup import validation, and an in-memory registry so workflows, reports, service tasks, and AI agents can start depending on stable Fabric concepts before specific database/connector executors are added.
The current implementation also includes DefaultAiFabricQueryService, which
resolves a dataset or relationship into a governed query plan. The plan includes
the dataset definition, parameters, logical entities, semantic relationships,
physical objects, physical sources, linked connectors, query model, cache policy,
materialization flag, normalized source capabilities, and relationship execution
plans.
This query service does not yet execute SQL, APIs, files, or connector calls. It is the stable planning layer that those executors will consume.
The relationship execution plan is important for scale. A dataset can contain relationships that cross PostgreSQL, Oracle, REST APIs, SaaS connectors, n8n, Make.com, files, and event streams. Fabric does not force those into one SQL join model. Instead, each relationship plan declares:
resolverType:same-database,cross-database,api,connector,file,event,materialized,ai-assisted, ormanual.objectIds: physical objects involved in that relationship.sourceIds: physical systems involved in that relationship.connectorIds: connector registry ids needed by the resolver.mappingandpolicy: the relationship mapping and safety/cache policy.materializationRecommended: whether workers should prefer a durable materialized result over live fan-out.
XML Format
<aiFabricCatalog version="1">
<sources>
<source id="crm-postgres" type="RELATIONAL_DATABASE">
<name>CRM PostgreSQL</name>
<connectionReference>secret:crm-postgres</connectionReference>
<readOnly>true</readOnly>
<metadata>{"engine":"postgresql","supportsSql":true}</metadata>
</source>
</sources>
<objects>
<object id="crm-postgres.customers" sourceId="crm-postgres" type="TABLE">
<schema>{"customer_number":"string","email":"string"}</schema>
</object>
</objects>
<entities>
<entity id="customer">
<objectIds>crm-postgres.customers</objectIds>
<attributes>{"naturalKey":"customer_number"}</attributes>
</entity>
</entities>
<relationships>
<relationship id="customer-invoices" fromEntityId="customer" toEntityId="invoice" strategy="API_LOOKUP">
<mapping>{"left":"customer.customer_number","right":"billing.invoices.customerNumber"}</mapping>
<policy>{"cacheSeconds":120}</policy>
</relationship>
</relationships>
<datasets>
<dataset id="customer-360">
<entityIds>customer,invoice</entityIds>
<relationshipIds>customer-invoices</relationshipIds>
<materialized>true</materialized>
</dataset>
</datasets>
</aiFabricCatalog>
Seed Catalog
conf/ai-fabric/platform-connectors.xml currently declares:
- relational databases: PostgreSQL CRM and Oracle ERP
- APIs/connectors: REST billing, Salesforce, n8n, and Make
- file and event sources: contracts drive and workflow events
- logical entities: customer, order, invoice, automation run, contract, and process event
- relationships spanning database-to-database, API lookup, connector lookup, file lookup, and event-derived mapping
customer-360as the first governed cross-source datasetplatform-diagnostic-echoas the first executable connector-backed materialized dataset
Extension Authoring
Fabric packs can be authored by configuration. The preview API generates a complete XML catalog file for a cross-source relationship:
- primary source, object, and logical entity
- related source, object, and logical entity
- semantic relationship between the two entities
- reusable dataset over both entities
flowchart TD
A["POST /api/ai-fabric/extension-pack/preview"] --> B["AiFabricExtensionAuthoringService"]
B --> C["catalogXml"]
C --> D["conf/ai-fabric/<pack>.xml"]
D --> E["XmlAiFabricCatalogLoader"]
E --> F["AiFabricCatalogImporter"]
F --> G["AiFabricRegistryService"]
Example request:
POST /api/ai-fabric/extension-pack/preview
Content-Type: application/json
X-Actor-Id: designer
{
"packName": "finance-fabric",
"sourceId": "finance-postgres",
"sourceName": "Finance PostgreSQL",
"sourceType": "RELATIONAL_DATABASE",
"connectionReference": "secret:finance-postgres",
"sourceMetadataJson": "{\"engine\":\"postgresql\",\"category\":\"finance\"}",
"objectId": "finance-postgres.payments",
"objectType": "TABLE",
"objectSchemaJson": "{\"payment_id\":\"string\",\"invoice_id\":\"string\",\"amount\":\"number\"}",
"entityId": "payment",
"entityName": "Payment",
"relatedSourceId": "billing-api",
"relatedSourceType": "REST_API",
"relatedConnectionReference": "connector:billing-api",
"relatedObjectId": "billing-api.invoices",
"relatedObjectType": "API_RESOURCE",
"relatedEntityId": "invoice",
"relationshipId": "payment-invoice",
"relationshipStrategy": "API_LOOKUP",
"relationshipMappingJson": "{\"left\":\"finance-postgres.payments.invoice_id\",\"right\":\"billing-api.invoices.invoice_id\"}",
"datasetId": "payment-360",
"materialized": true
}
The response contains:
packNamecatalogPath, usuallyconf/ai-fabric/<packName>.xmlcatalogXml, the generated standard Fabric XMLnextSteps
The preview endpoint is intentionally non-mutating. Platform administrators can
review the generated XML, save it under conf/ai-fabric/, configure the
referenced secrets/connectors, and restart or reload the catalog.
All JSON-bearing fields must be valid JSON objects. JSON null, arrays, and
invalid JSON are rejected with AI_FABRIC_EXTENSION_SCHEMA_INVALID.
Connector Links
Fabric sources may reference connectors using:
connector:<connector-id>
Example:
<source id="n8n" type="CONNECTOR">
<connectionReference>connector:n8n</connectionReference>
</source>
When AiFabricQueryService.resolveDataset("customer-360", parameters) runs, it
looks up those connector references in ConnectorRegistryService and includes a
connectorLinks section in the returned VariableMap.
flowchart TD
A["Dataset: customer-360"] --> B["Logical Entities"]
B --> C["Physical Objects"]
C --> D["Sources"]
D --> E["connector:n8n"]
D --> F["connector:make"]
D --> G["connector:salesforce"]
E --> H["ConnectorRegistryService"]
F --> H
G --> H
Approved Database Queries
Database-backed Fabric and report workflows should call approved query IDs through the connector layer rather than embedding SQL in BPMN, forms, or AI prompts.
The first executable path is:
flowchart LR
A["service.data.query"] --> B["connector-jdbc"]
B --> C["ConnectorExecutionService"]
C --> D["JDBC ConnectorExecutor"]
D --> E["ApprovedQueryRegistryService"]
E --> F["conf/queries/*.xml"]
D --> G["Database"]
This keeps relationships and datasets database-agnostic while still allowing safe, reviewed SQL per engine.
Approved queries can declare data-exposure policy in metadata:
{
"pii": ["email", "display_name"],
"aiExposure": "masked"
}
The JDBC approved-query executor enforces this before rows leave the connector:
piicolumns are masked as[MASKED]when masking is enabled.aiExposure=metadata-onlysuppresses rows and returns only execution metadata.aiExposure=blockedrejects execution.- execution metadata records masking and suppression decisions.
This is the first Fabric safety gate. It protects data before the same query output can feed workflow variables, reports, connectors, or AI Gateway tasks.
Approved queries can also opt into connector-level result caching:
{
"cacheSeconds": 300
}
The JDBC executor caches the post-policy result, so cached rows preserve masking
and suppression decisions. The cache key includes connector id, approved query
id, effective parameters, and maxRows. Callers can force a fresh read with
bypassCache=true or noCache=true.
Dataset Materialization
The first materialization path is available through:
service.data.materialize.dataset
This task uses DatasetMaterializationService, which resolves the dataset
through AiFabricQueryService and returns a deterministic materialization run
artifact.
Default behavior is PLAN_ONLY: it validates the dataset, resolves entities,
relationships, objects, sources, connector links, query model, and cache policy,
then returns those details as workflow variables. This gives workers, reports,
and storage executors a stable contract.
Datasets can opt into executable materialization by declaring
queryModel.materializationSteps. Each step calls the connector layer, which
keeps Fabric database-agnostic and lets the same model execute JDBC approved
queries, REST connectors, SaaS connectors, or future file/event executors.
<dataset id="support-360">
<name>Support 360</name>
<entityIds>support-user</entityIds>
<materialized>true</materialized>
<queryModel>{
"materializationSteps": [
{
"name": "load-support-users",
"connectorId": "postgresql",
"operationId": "run-approved-query",
"input": {
"queryId": "identity.active-users",
"parameters": {
"active": true,
"customerNumber": "{{parameters.customerNumber}}"
}
},
"options": {
"maxRows": 25
}
}
]
}</queryModel>
</dataset>
Supported step fields:
nameorid: human-readable step identifier for audit evidence.enabled: optional boolean; disabled steps are skipped.connectorId: connector registry id, for examplepostgresql,salesforce,google-sheets, or a custom connector.operationId: connector operation id. JDBC approved-query datasets usually userun-approved-query.input: connector inputVariableMap.options: connector execution options.
Step input and options can reference materialization request parameters:
$parametersinjects the full parameter map.$parameters.customerNumberinjects one parameter.{{parameters.customerNumber}}also injects one parameter.
When executable steps are present, materialization metadata uses
executionMode=CONNECTOR_STEPS. Successful materialized datasets return status
MATERIALIZED; failed connector steps return status FAILED and save the
partial execution evidence.
Each materialization run is saved through DatasetMaterializationRunRepository.
The default API configuration uses a JDBC implementation backed by:
ai_fabric_materialization_runs
This table stores the run id, dataset id, status, materialized flag, plan JSON, metadata JSON, start time, and completion time. The repository boundary allows the platform to swap storage later without changing workflow or service-task code.
For datasets marked <materialized>true</materialized>, successful connector
step output is also saved through MaterializedDatasetRecordRepository. The
default JDBC implementation stores records in:
ai_fabric_materialized_records
Records are extracted from connector output in this order:
- If
output.rowsis present, each row becomes one materialized record. - If no rows are present but the connector output is non-empty, the full output becomes one materialized record.
Each record stores the dataset id, run id, record key, step name, payload JSON,
record metadata JSON, and materialization timestamp. The metadata keeps the
connector id, operation id, external connector reference, row index, and
connector metadata. Record keys use stepName:index; if repeated step names
would collide, the service adds a numeric suffix.
Repository callers can read records by run id or ask for the latest records for a dataset. This gives reports, downstream workflow steps, and future cache refresh workers a durable data boundary without binding Fabric to one database engine.
Output includes:
datasetRunIddatasetIdmaterializationStatusmaterializedplanmetadatastartedAtcompletedAt
For executable materialized datasets, metadata also includes
materializedRecordCount.
When an idempotencyKey is supplied, the run id is deterministic:
mat-<datasetId>-<idempotencyKey>
HTTP API
Fabric is exposed through authenticated platform APIs under:
/api/ai-fabric
The API is intentionally split between catalog viewing, query-plan resolution, and materialization so permissions can be granted independently.
Catalog Endpoints
GET /api/ai-fabric/sources
GET /api/ai-fabric/sources/{sourceId}
GET /api/ai-fabric/objects
GET /api/ai-fabric/objects/{objectId}
GET /api/ai-fabric/entities
GET /api/ai-fabric/entities/{entityId}
GET /api/ai-fabric/entities/{entityId}/relationships
GET /api/ai-fabric/relationships
GET /api/ai-fabric/relationships/{relationshipId}
GET /api/ai-fabric/datasets
GET /api/ai-fabric/datasets/{datasetId}
GET /api/ai-fabric/graph
GET /api/ai-fabric/readiness
GET /api/ai-fabric/search?q=customer
POST /api/ai-fabric/extension-pack/preview
These endpoints require:
AI_FABRIC_VIEW
Relationship Graph
GET /api/ai-fabric/graph?datasetId=customer-360&depth=2
GET /api/ai-fabric/graph?sourceId=salesforce
GET /api/ai-fabric/graph?objectId=crm-postgres.customers
GET /api/ai-fabric/graph?entityId=customer
The graph endpoint is the topology view for Fabric. It returns:
nodes: source, object, entity, relationship, and dataset nodes.edges: source-to-object, object-to-entity, entity-to-relationship, and dataset usage edges.relationshipPlans: resolver plans for included relationships, including connector ids and whether materialization is recommended.summary: counts, connector ids, source types, relationship strategies, and materialization recommendation count.warnings: missing filter targets such as an unknown source, object, entity, or dataset id.
Use this endpoint for admin topology screens, impact analysis, relationship designer canvases, and dependency review before changing a connector, table, API resource, dataset, or materialization policy.
This endpoint requires:
AI_FABRIC_VIEW
Readiness Report
GET /api/ai-fabric/readiness
The readiness endpoint is the operational health check for Fabric catalog packs. It does not execute queries. It inspects the loaded catalog and linked connector registry so administrators can see whether the model is safe to use from workflow designs, reports, agents, and materialization jobs.
The report includes:
- counts for sources, objects, logical entities, relationships, and datasets
- source/object/relationship strategy inventory
- connector-linked source count
- materialized dataset count
- executable materialized dataset count
- readiness issues
productionReady, which isfalsewhen any readiness issue has severityERROR
Current readiness checks include:
- source connector references must exist in
conf/connectors - sources should declare
connectionReference - sources should declare
metadata.categoryormetadata.domain - objects should declare schemas
- entities must map to physical objects and should declare a natural or primary key
- relationships must point to existing entities and should declare mapping and policy
- datasets must contain at least one entity or relationship
- materialized datasets should declare
queryModel.materializationStepswhen they are expected to execute rather than run in plan-only mode - datasets should declare cache policy for reuse by reports, workflows, and AI tasks
Example response shape:
{
"sourceCount": 8,
"objectCount": 8,
"entityCount": 6,
"relationshipCount": 5,
"datasetCount": 2,
"connectorLinkedSourceCount": 3,
"materializedDatasetCount": 2,
"executableMaterializedDatasetCount": 1,
"bySourceType": {
"CONNECTOR": 3,
"RELATIONAL_DATABASE": 2
},
"issues": [
{
"severity": "WARN",
"code": "MATERIALIZATION_STEPS_MISSING",
"itemType": "dataset",
"itemId": "customer-360"
}
],
"productionReady": true
}
Warnings are allowed during modeling. Errors should block release of an Fabric pack because they indicate missing references, usually a connector, source, object, entity, relationship, or dataset target.
Resolve A Dataset Plan
POST /api/ai-fabric/datasets/customer-360/resolve
Content-Type: application/json
X-Actor-Id: worker
{
"parameters": {
"values": {
"customerNumber": "C-100"
}
}
}
The response is a VariableMap. Its values include the dataset definition,
parameters, entities, relationships, objects, sources, connector links, query
model, cache policy, materialization flag, source capabilities, and relationship
plans.
Example response sections:
{
"sourceCapabilities": {
"salesforce": {
"sourceType": "CONNECTOR",
"connectorId": "salesforce",
"connectorProtocol": "REST",
"operationCount": 2
}
},
"relationshipPlans": [
{
"relationshipId": "customer-orders",
"resolverType": "cross-database",
"sourceIds": ["crm-postgres", "erp-oracle"],
"connectorIds": [],
"materializationRecommended": true
},
{
"relationshipId": "customer-automation-runs",
"resolverType": "connector",
"sourceIds": ["crm-postgres", "make", "n8n", "salesforce"],
"connectorIds": ["make", "n8n", "salesforce"]
}
]
}
This endpoint requires:
AI_FABRIC_QUERY
Resolve A Relationship Plan
POST /api/ai-fabric/relationships/customer-automation-runs/resolve
Content-Type: application/json
X-Actor-Id: worker
{
"leftSide": {
"values": {
"customerNumber": "C-100"
}
}
}
The response describes the relationship, endpoint entities, input side, mapping, policy, and relationship strategy.
This endpoint requires:
AI_FABRIC_QUERY
Materialize A Dataset Plan
POST /api/ai-fabric/datasets/customer-360/materialize
Content-Type: application/json
X-Actor-Id: worker
{
"parameters": {
"values": {
"customerNumber": "C-200"
}
},
"forceRefresh": true,
"idempotencyKey": "customer-200-refresh",
"options": {
"mode": "refresh"
}
}
Datasets without queryModel.materializationSteps run in PLAN_ONLY mode. A
dataset with executable steps calls the connector layer and saves each step
result into the materialization run plan under materializationResults.
This endpoint requires:
AI_FABRIC_MATERIALIZE
Read Materialized Records
Executable materialized datasets can be read back through authenticated API endpoints:
GET /api/ai-fabric/materialization-runs/mat-platform-diagnostic-echo-api-records/records?limit=100
X-Actor-Id: worker
GET /api/ai-fabric/datasets/platform-diagnostic-echo/materialized-records?limit=100
X-Actor-Id: worker
Both endpoints return MaterializedDatasetRecord items with dataset id, run id,
record key, step name, payload, metadata, and materialization timestamp. The run
endpoint is best when a workflow needs the exact output from the run it just
started. The dataset endpoint is best for reports and dashboards that want the
latest persisted dataset records.
The limit parameter defaults to 100, has a minimum effective value of 1,
and is capped at 500.
These endpoints require:
AI_FABRIC_VIEW
The default development roles grant Fabric permissions to designer and
worker. root has *.
Validation
AiFabricCatalogImporter validates references during import:
- objects must reference existing sources
- entities must reference existing objects
- relationships must reference existing entities
- datasets must reference existing entities and relationships
Invalid catalogs fail fast with AiFabricException codes such as
AI_FABRIC_ENTITY_OBJECT_NOT_FOUND.
Next steps:
- distributed materialization workers.
- materialized record pagination, filtering, and retention policies.