> ## 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. # Update package configuration > Updates the configuration and metadata of an existing package. This allows you to modify package settings, update the description, change the location, or update other package-level properties. The package must exist and be accessible. ## OpenAPI ````yaml /dataplane-public-api-doc.yaml patch /environments/{environmentName}/packages/{packageName} 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}: patch: tags: - packages summary: Update package configuration description: > Updates the configuration and metadata of an existing package. This allows you to modify package settings, update the description, change the location, or update other package-level properties. The package must exist and be accessible. operationId: update-package parameters: - name: environmentName in: path description: Name of the environment required: true schema: $ref: '#/components/schemas/IdentifierPattern' - name: packageName in: path description: Name of the package required: true schema: $ref: '#/components/schemas/IdentifierPattern' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/Package' responses: '200': description: Returns the package updated content: application/json: schema: $ref: '#/components/schemas/Package' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/InternalServerError' '501': $ref: '#/components/responses/NotImplemented' '503': $ref: '#/components/responses/ServiceUnavailable' components: schemas: IdentifierPattern: type: string pattern: ^[a-zA-Z0-9_-]+$ description: Standard identifier pattern for resource names Package: type: object description: >- Represents a Malloy package containing models, notebooks, and embedded databases properties: resource: type: string description: Resource path to the package name: type: string description: Package name description: type: string description: Package description location: type: string description: >- Package location, can be an absolute path or URI (e.g. github, s3, gcs, etc.) explores: type: array items: type: string description: >- Optional opt-in for curated discovery. When present, only these model file paths (relative to the package root) are listed via `listModels()`, and within-file discovery is filtered to each model's `export {}` closure. When absent or empty, every model is listed with its full source set (backward-compatible). Every other .malloy file still compiles for import/join resolution but is hidden from listings once `explores` is declared. Notebooks are always listed regardless of this field. exploresWarnings: type: array readOnly: true items: type: string description: >- Actionable messages for declared explores that do not resolve to a real model in this package (e.g. a misspelled path, or a notebook listed as an explore). Server-computed and read-only: it is ignored on create/update requests and only ever returned in responses. Present only when there are such problems. Loading is fail-safe — the unresolved entry simply lists nothing rather than exposing everything — so this is the signal that a package is misconfigured; publishing such a package is rejected. warnings: type: array readOnly: true description: >- Non-fatal render-tag findings collected when the package loaded: a render annotation (e.g. `# big_value` or `# currency`) misconfigured for the field it sits on, so it renders as "[object Object]" or an inline error at query time but does not stop the model compiling or the package loading. Server-computed and read-only: ignored on create/update requests and only returned in responses. Present only when there are such findings. items: type: object properties: model: type: string description: Package-relative path of the model the finding is on. target: type: string description: >- The query or view the finding sits on, e.g. `by_carrier` or `flights -> by_carrier`. message: type: string description: The render validator's description of the problem. severity: type: string enum: - error - warn description: >- Finding severity. Currently only `error`-severity render findings are surfaced here; lower-severity findings remain on the query-time `renderLogs` surface. queryableSources: type: string enum: - declared - all description: >- Controls whether the discovery surface is also a query boundary. `"declared"` (the default) makes queryable == discoverable: when `explores` is declared, only `explores` model files — and within them only the `export {}` closure — are valid top-level query targets; every other source still compiles, imports, joins, and extends but is not directly queryable (denied with 404). `"all"` decouples them: `explores`/`export {}` gate discovery only and every compiled source stays directly queryable. When `explores` is absent there is no curated surface, so both modes are equivalent (everything queryable). Invalid values fall back to `"declared"`. Identity-based access is a separate concern — see `#(authorize)`. manifestLocation: type: - string - 'null' description: > URI (gs:// or s3://) of the externally-computed manifest for this package. On (re)load the publisher reads it and binds persist references (sourceEntityId -> physicalTableName). Null = serve live. scope: type: string enum: - version - package description: >- Package-level materialization scope mode, declared at the malloy-publisher.json manifest root. Governs the lifetime/ownership of every persisted source and dimension index in the package, and replaces the removed per-source/per-dimension `sharing` annotation: - `version`: materializations are owned by (scoped to) the package version; no cross-version reuse. Cadence is a single package-level `materialization.schedule` OR freshness (never both). - `package`: materializations may be reused across the package's own versions when fresh; cadence is freshness only (no `schedule` allowed). Null/absent = unknown this request; the control plane treats it as the platform default (`package`) and never as a scope change. See docs/persistence.md §3.1. materialization: oneOf: - $ref: '#/components/schemas/PackageMaterializationConfig' - type: 'null' description: | Package-level Malloy Persistence policy declared in malloy-publisher.json. The control plane reads it to drive scheduled re-materialization. The object is present whenever the package is loaded (with `schedule: null` when none is declared), so its presence is the authoritative manifest policy; null/absent means only that metadata was unavailable this request, which the control plane treats as "unknown" (never a schedule removal). A published version's schedule is persisted write-once and thereafter only verified, so it cannot self-wipe on a later build. manifestBindingStatus: type: string readOnly: true enum: - unbound - bound - live_fallback description: >- Server-computed, read-only: whether the configured build manifest is currently bound to this package's served models. `unbound` = no manifest configured, so the package serves live. `bound` = a manifest was fetched and applied, so persist sources route to their materialized physical tables. `live_fallback` = a `manifestLocation` is configured but the fetch/bind failed or timed out, so the package is serving live despite intending to be materialized-routed. Lets the caller confirm the publisher actually bound the configured manifest rather than inferring it from logs. manifestEntryCount: type: integer readOnly: true description: >- Server-computed, read-only: number of sourceEntityId -> physical-table entries currently bound (0 when unbound or on live fallback). boundManifestUri: type: - string - 'null' readOnly: true description: >- Server-computed, read-only: the manifest URI actually bound to the served models. Usually equals `manifestLocation`, but can differ after an in-memory auto-load following a materialization build (no URI), in which case it is null. Null whenever the package is unbound. buildPlan: oneOf: - $ref: '#/components/schemas/BuildPlan' - type: 'null' readOnly: true description: >- Server-computed, read-only: the persist build plan for this package version (per-source sourceEntityId, output columns, build SQL, dependency graphs), exposed as a deterministic property of the compiled package. A caller reads it directly off the load/get-package response, assigns physical names/identity per source, and issues a single build call (see `CreateMaterializationRequest.buildInstructions`) — no separate plan round-trip. The plan is a pure function of the compiled model + connection config (no warehouse access), so it is stable for a given (package version, connection config). Returned by default whenever the package is compiled; null only when the package declares no persist source. PackageMaterializationConfig: type: object description: >- Package-level Malloy Persistence policy from malloy-publisher.json's `materialization` block. Surfaced verbatim so the control plane can drive scheduled version-level re-materialization without re-reading the package files. properties: schedule: type: - string - 'null' description: >- 5-field UNIX cron controlling how often the control plane re-materializes this package's published versions. Null/absent = no scheduled re-materialization (publish / on-demand only). A cron is valid only in `scope: version` mode and is mutually exclusive with any freshness declaration in the package (package/model-file/source/ index). A cron on a `scope: package` package, or alongside any freshness, is rejected at publish (declare `materialization.freshness.window` instead). See docs/persistence.md §9.4. freshness: oneOf: - $ref: '#/components/schemas/Freshness' - type: 'null' description: >- The manifest's `materialization.freshness` block, verbatim. Null = no freshness policy declared. `window` is the control plane's refresh objective for the package's materialized sources; `fallback` is the declared query-time behavior when the objective is missed. The publisher only surfaces the values — the control plane owns the scheduling and gating logic. BuildPlan: type: object description: > The package's persist build plan. Mirrors Malloy's native build plan plus the minimal per-source detail a caller needs to assign identity/naming/realization. Lineage, policy, and connection capability are intentionally omitted until they carry real data. required: - graphs - sources properties: graphs: type: array description: Dependency-ordered build graphs, one per connection. items: $ref: '#/components/schemas/BuildGraph' sources: type: object description: Map of sourceID ("sourceName@modelURL") to per-source plan. additionalProperties: $ref: '#/components/schemas/PersistSourcePlan' 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 Freshness: type: object description: >- Freshness policy declared in malloy-publisher.json's `materialization.freshness` block. Fields are surfaced verbatim; invalid values are dropped (reported as absent), never defaulted. properties: window: type: string description: >- Maximum acceptable staleness of the package's materialized sources, as a duration string (e.g. "24h"). The control plane schedules refreshes to meet it. fallback: type: string enum: - live - stale_ok - fail description: >- Declared query-time behavior when the freshness window is missed: serve live, serve the stale table, or fail the query. BuildGraph: type: object required: - connectionName - nodes properties: connectionName: type: string nodes: type: array description: >- Leveled build nodes; each inner array is one parallelizable level, levels run in order. items: type: array items: $ref: '#/components/schemas/BuildNode' PersistSourcePlan: type: object required: - name - sourceID - connectionName - sourceEntityId - sql - columns properties: name: type: string sourceID: type: string connectionName: type: string dialect: type: string sourceEntityId: type: string description: >- Stable, content-addressed identity of this persisted source. Today a deterministic SHA-256 hex digest (`mkBuildID`) over the source's connection `fingerprint` and its canonical compiled SQL — deliberately independent of package version, so it changes only when the source's data identity changes. (Folding source scope into the address and moving to a UUID5 form is planned but not yet shipped.) Consumers treat it as an opaque token and use the supplied value verbatim. sql: type: string description: >- The source's build SQL (with the build manifest applied for upstream rewrites). refresh: type: - string - 'null' description: >- The source's declared `#@ persist ... refresh=...` value ("full" | "incremental"), reported verbatim; null = unset. Metadata pass-through — inert to the publisher today. freshness: oneOf: - $ref: '#/components/schemas/Freshness' - type: 'null' description: >- The source's EFFECTIVE freshness objective after most-specific-wins resolution (source > model-file > package). Null = unset at every level; the control plane applies the platform default. Reported verbatim (invalid fields dropped, never defaulted). columns: type: array description: Output schema of the source. items: $ref: '#/components/schemas/Column' annotationFields: type: object additionalProperties: type: string description: >- All key=value fields of the source's `#@ persist` annotation (e.g. `name`, `realization`). The control plane uses `name` as the materialized table name — it may carry a dialect container path (`dataset.table` / `project.dataset.table`) — falling back to the Malloy source name when absent. modelPath: type: string description: >- Package-relative path of the `.malloy` model that declares this source (e.g. `order_rollup.malloy`). The source's sourceID embeds an absolute `file://` modelURL with no package boundary, so this is the only place the relative path is exposed; the control plane uses it to let the build-plan DAG deep-link a source back to its model. BuildNode: type: object required: - sourceID properties: sourceID: type: string description: sourceName@modelURL dependsOn: type: array description: Upstream sourceIDs in this graph. items: type: string Column: type: object description: Database column definition properties: name: type: string description: Name of the column type: type: string description: Data type of the column responses: BadRequest: description: >- The request was malformed or cannot be performed given the current state of the system content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: Unauthorized - authentication required content: application/json: schema: $ref: '#/components/schemas/Error' NotFound: description: The specified resource was not found content: application/json: schema: $ref: '#/components/schemas/Error' InternalServerError: description: The server encountered an internal error content: application/json: schema: $ref: '#/components/schemas/Error' NotImplemented: description: The requested operation is not implemented content: application/json: schema: $ref: '#/components/schemas/Error' ServiceUnavailable: description: > The service is temporarily unable to accept the request. Possible causes: * Initialization or draining state (rolling updates, graceful shutdown). * Memory back-pressure — the publisher's RSS crossed the high-water mark derived from PUBLISHER_MAX_MEMORY_BYTES and PUBLISHER_MEMORY_HIGH_WATER_FRACTION, so new queries are rejected until RSS drops below the low-water mark (PUBLISHER_MEMORY_LOW_WATER_FRACTION). * Per-pod query concurrency cap reached — PUBLISHER_MAX_CONCURRENT_QUERIES in-flight queries are already running on this pod. Clients should retry with backoff; under sustained pressure, scale out, raise PUBLISHER_MAX_MEMORY_BYTES / PUBLISHER_MAX_CONCURRENT_QUERIES, or refine the offending queries. content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT ````