> ## Documentation Index > Fetch the complete documentation index at: https://docs.credibledata.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a materialization > Creates a materialization and starts building. Behavior depends on the request body (see CreateMaterializationRequest): * Orchestrated build — supply `buildInstructions`. The publisher builds directly into the caller-assigned names derived from the package's already-compiled build plan (read off `Package.buildPlan`). Returns the materialization already building. * Auto-run (standalone, default) — omit `buildInstructions`; the publisher self-assigns names and runs all phases in one pass. ## OpenAPI ````yaml /dataplane-public-api-doc.yaml post /environments/{environmentName}/packages/{packageName}/materializations openapi: 3.1.0 info: title: Malloy Publisher - Semantic Model Serving API description: > The Malloy Publisher - Semantic Model Serving API provides comprehensive access to Malloy packages and their associated resources. A Malloy package is a directory containing Malloy models (.malloy files), Malloy notebooks (.malloynb files), and embedded databases (.parquet files) with a malloy-publisher.json manifest at the package's root directory. ## Key Features - **Environment Management**: Create and manage environments with their associated packages and connections - **Package Lifecycle**: Full CRUD operations for Malloy packages and their versions - **Model & Notebook Access**: Retrieve and execute Malloy models and notebooks - **Connection Management**: Secure database connection configuration and testing - **Query Execution**: Execute queries against models and retrieve results - **Watch Mode**: Real-time file watching for development workflows ## Resource Hierarchy The API follows a hierarchical resource structure: ``` Environments ├── Connections └── Packages ├── Models ├── Notebooks └── Databases ``` For examples, see the Malloy samples packages (https://github.com/malloydata/malloy-samples) repository. version: v0 servers: - url: https://{organization}.data.credibledata.com/api/v0/ description: Production API server variables: organization: default: demo description: Your organization subdomain security: - bearerAuth: [] tags: - name: publisher description: Publisher status and health check operations - name: environments description: >- Environment lifecycle management including creation, configuration, and deletion of data modeling environments - name: connections description: >- Database connection management for secure data source configuration and access - name: packages description: >- Package management for Malloy data models, including versioning and distribution - name: models description: Malloy model access and compilation operations - name: notebooks description: Malloy notebook access and execution operations - name: pages description: Static HTML pages (in-package data apps) - name: databases description: Embedded database management and access - name: watch-mode description: Real-time file watching for development workflows - name: materializations description: Package-level materializations for persisting Malloy sources paths: /environments/{environmentName}/packages/{packageName}/materializations: post: tags: - materializations summary: Create a materialization description: > Creates a materialization and starts building. Behavior depends on the request body (see CreateMaterializationRequest): * Orchestrated build — supply `buildInstructions`. The publisher builds directly into the caller-assigned names derived from the package's already-compiled build plan (read off `Package.buildPlan`). Returns the materialization already building. * Auto-run (standalone, default) — omit `buildInstructions`; the publisher self-assigns names and runs all phases in one pass. operationId: create-materialization parameters: - $ref: '#/components/parameters/environmentName' - $ref: '#/components/parameters/packageName' requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateMaterializationRequest' responses: '201': description: Materialization created content: application/json: schema: $ref: '#/components/schemas/Materialization' '404': $ref: '#/components/responses/NotFound' '409': description: Package already has an active materialization content: application/json: schema: $ref: '#/components/schemas/Error' components: parameters: environmentName: name: environmentName in: path required: true description: Name of the environment schema: type: string packageName: name: packageName in: path required: true description: Name of the package schema: type: string schemas: CreateMaterializationRequest: type: object description: >- Options for starting a materialization. Two modes — (1) auto-run (default), omit `buildInstructions` and the publisher self-assigns names and runs all phases in one pass; (2) orchestrated build, supply `buildInstructions` and the publisher builds directly into the caller-assigned names from the package's already-compiled build plan (read off `Package.buildPlan`). properties: buildInstructions: oneOf: - $ref: '#/components/schemas/BuildInstructions' - type: 'null' description: >- Orchestrated build. When present, the publisher creates the materialization already building these caller-assigned sources (table id, physical name, realization) into the exact names provided — the caller derived these instructions from `Package.buildPlan` up front. Omit for auto-run (the publisher self-assigns names and builds all persist sources). forceRefresh: type: boolean default: false description: Build a new table even when a source's sourceEntityId is unchanged. sourceNames: type: array items: type: string description: >- Restrict the plan/build to these persist source names. Omit = all persist sources. Materialization: type: object description: A record of one materialization run for a package. properties: id: type: string environmentId: type: string packageName: type: string status: $ref: '#/components/schemas/MaterializationStatus' manifest: oneOf: - $ref: '#/components/schemas/BuildManifest' - type: 'null' description: Build output. Null until status = MANIFEST_FILE_READY. startedAt: type: - string - 'null' format: date-time completedAt: type: - string - 'null' format: date-time error: type: - string - 'null' description: Error message if the materialization failed metadata: type: - object - 'null' description: >- Materialization metadata including build options, source counts, and durations createdAt: type: string format: date-time updatedAt: type: string format: date-time Error: type: object description: Standard error response format properties: message: type: string description: Human-readable error message describing what went wrong details: type: string description: Additional error details or context required: - message BuildInstructions: type: object description: Build input. Per-source instructions assigned by the caller. required: - sources properties: sources: type: array items: $ref: '#/components/schemas/BuildInstruction' referenceManifest: type: array description: >- Already-materialized persist upstreams the built sources may reference but which are NOT rebuilt in this run. The publisher seeds the build Manifest with these so a downstream source's upstream persist reference resolves to the existing physical table instead of recomputing it live. Only consumed on the orchestrated (buildInstructions) path; auto-run seeds its own reference set from the most-recent manifest. items: $ref: '#/components/schemas/ManifestReference' strictUpstreams: type: boolean default: false description: >- When true, a persist upstream that is neither built here nor present in referenceManifest fails the build (compiler strict mode) instead of silently recomputing it live. Per-unit dispatch should set this true. MaterializationStatus: type: string description: Phase-aware status of a materialization run. enum: - PENDING - MANIFEST_ROWS_READY - MANIFEST_FILE_READY - FAILED - CANCELLED BuildManifest: type: object description: >- Build output. Maps each sourceEntityId a build produced to its physical table. Returned inline; the caller persists it. properties: builtAt: type: string format: date-time entries: type: object additionalProperties: $ref: '#/components/schemas/ManifestEntry' description: Map of sourceEntityId to manifest entry. strict: type: boolean description: Whether unresolved references should error. BuildInstruction: type: object required: - sourceEntityId - materializedTableId - physicalTableName - realization properties: sourceEntityId: type: string description: >- Identifies which planned source this instruction is for (matches PersistSourcePlan.sourceEntityId). sourceID: type: string description: >- Optional convenience echo of "sourceName@modelURL"; sourceEntityId is authoritative. materializedTableId: type: string description: >- Caller-assigned surrogate id for the materialized table about to be produced. physicalTableName: type: string description: >- Fully-qualified, dialect-quoted table name to create. The publisher writes here verbatim. realization: $ref: '#/components/schemas/Realization' ManifestReference: type: object description: >- A reference to an already-materialized persist upstream that the built sources may read but which is not rebuilt in this run. required: - sourceEntityId - physicalTableName properties: sourceEntityId: type: string description: >- The upstream's content id AS REPORTED BY THE PUBLISHER in PersistSourcePlan.sourceEntityId. It MUST equal what the compiler recomputes for the manifest lookup (mkBuildID over the upstream's manifest-ignorant SQL); do not substitute any other identity here. physicalTableName: type: string description: Fully-qualified physical table the upstream currently serves. ManifestEntry: type: object description: A single entry in the build manifest. required: - sourceEntityId - physicalTableName properties: sourceEntityId: type: string sourceName: type: string materializedTableId: type: string description: Echoes the caller-assigned id from the BuildInstruction. physicalTableName: type: string description: Name of the materialized table. connectionName: type: string realization: $ref: '#/components/schemas/Realization' rowCount: type: - integer - 'null' Realization: type: string enum: - SNAPSHOT - COPY description: SNAPSHOT = warehouse clone/snapshot; COPY = CREATE TABLE AS SELECT. responses: NotFound: description: The specified resource was not found content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT ````