Inflow.aiDocs

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, or manual.
  • objectIds: physical objects involved in that relationship.
  • sourceIds: physical systems involved in that relationship.
  • connectorIds: connector registry ids needed by the resolver.
  • mapping and policy: 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-360 as the first governed cross-source dataset
  • platform-diagnostic-echo as 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:

  • packName
  • catalogPath, usually conf/ai-fabric/<packName>.xml
  • catalogXml, the generated standard Fabric XML
  • nextSteps

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.

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:

  • pii columns are masked as [MASKED] when masking is enabled.
  • aiExposure=metadata-only suppresses rows and returns only execution metadata.
  • aiExposure=blocked rejects 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:

  • name or id: human-readable step identifier for audit evidence.
  • enabled: optional boolean; disabled steps are skipped.
  • connectorId: connector registry id, for example postgresql, salesforce, google-sheets, or a custom connector.
  • operationId: connector operation id. JDBC approved-query datasets usually use run-approved-query.
  • input: connector input VariableMap.
  • options: connector execution options.

Step input and options can reference materialization request parameters:

  • $parameters injects the full parameter map.
  • $parameters.customerNumber injects 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.rows is 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:

  • datasetRunId
  • datasetId
  • materializationStatus
  • materialized
  • plan
  • metadata
  • startedAt
  • completedAt

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 is false when any readiness issue has severity ERROR

Current readiness checks include:

  • source connector references must exist in conf/connectors
  • sources should declare connectionReference
  • sources should declare metadata.category or metadata.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.materializationSteps when 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.

Try “document generation”, “integrations” or “first form”.