Skip to content

docs(publisher): fix project→environment API drift in publishing guides #328

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
ofermend wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

docs(publisher): fix project→environment API drift in publishing guides #328

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 15 additions & 15 deletions src/documentation/user_guides/publishing/connections.malloynb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ Publisher uses `publisher.config.json` for database connections. This file lives

```json
{
"projects": [
"environments": [
{
"name": "default",
"connections": [
Expand Down Expand Up @@ -53,7 +53,7 @@ For packages with embedded parquet/CSV files, **no connection configuration is n

```json
{
"projects": [
"environments": [
{
"name": "default",
"packages": [
Expand Down Expand Up @@ -92,7 +92,7 @@ DuckDB can federate queries to external databases (BigQuery, Snowflake, PostgreS

```json
{
"projects": [
"environments": [
{
"name": "default",
"connections": [
Expand Down Expand Up @@ -128,7 +128,7 @@ source: events is duckdb.table('my_bq.my_dataset.events')

```json
{
"projects": [
"environments": [
{
"name": "default",
"connections": [
Expand Down Expand Up @@ -162,7 +162,7 @@ source: events is duckdb.table('my_bq.my_dataset.events')

```json
{
"projects": [
"environments": [
{
"name": "default",
"connections": [
Expand Down Expand Up @@ -219,7 +219,7 @@ source: events is duckdb.table('my_bq.my_dataset.events')

```json
{
"projects": [
"environments": [
{
"name": "default",
"connections": [
Expand Down Expand Up @@ -248,7 +248,7 @@ Embed the service account JSON directly in the config:

```json
{
"projects": [
"environments": [
{
"name": "default",
"connections": [
Expand All @@ -272,7 +272,7 @@ Embed the service account JSON directly in the config:

```json
{
"projects": [
"environments": [
{
"name": "default",
"connections": [
Expand All @@ -299,7 +299,7 @@ Embed the service account JSON directly in the config:

```json
{
"projects": [
"environments": [
{
"name": "default",
"connections": [
Expand All @@ -326,7 +326,7 @@ Embed the service account JSON directly in the config:

```json
{
"projects": [
"environments": [
{
"name": "default",
"connections": [
Expand Down Expand Up @@ -355,7 +355,7 @@ Embed the service account JSON directly in the config:

```json
{
"projects": [
"environments": [
{
"name": "default",
"connections": [
Expand Down Expand Up @@ -383,7 +383,7 @@ Embed the service account JSON directly in the config:

```json
{
"projects": [
"environments": [
{
"name": "default",
"connections": [
Expand Down Expand Up @@ -411,7 +411,7 @@ Embed the service account JSON directly in the config:

```json
{
"projects": [
"environments": [
{
"name": "default",
"connections": [
Expand All @@ -436,11 +436,11 @@ For Presto, use `"type": "presto"` with the same configuration options.

## Multi-Environment Configuration

You can configure multiple projects for different environments:
You can configure multiple environments (for example, staging and production):

```json
{
"projects": [
"environments": [
{
"name": "staging",
"connections": [
Expand Down
10 changes: 5 additions & 5 deletions src/documentation/user_guides/publishing/mcp_agents.malloynb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -94,16 +94,16 @@ Publisher exposes these tools to AI agents:

| Tool | Parameters | Description |
|------|------------|-------------|
| `malloy_projectList` | — | List all available projects |
| `malloy_packageList` | `projectName` | List packages in a project |
| `malloy_packageGet` | `projectName`, `packageName` | Get models in a package |
| `malloy_modelGetText` | `projectName`, `packageName`, `modelPath` | Get raw model source code |
| `malloy_environmentList` | — | List all available environments |
| `malloy_packageList` | `environmentName` | List packages in an environment |
| `malloy_packageGet` | `environmentName`, `packageName` | Get models in a package |
| `malloy_modelGetText` | `environmentName`, `packageName`, `modelPath` | Get raw model source code |

### Query Execution

| Tool | Parameters | Description |
|------|------------|-------------|
| `malloy_executeQuery` | `projectName`, `packageName`, `modelPath`, `query` | Run a Malloy query, returns JSON results |
| `malloy_executeQuery` | `environmentName`, `packageName`, `modelPath`, `query` | Run a Malloy query, returns JSON results |

---

Expand Down
18 changes: 9 additions & 9 deletions src/documentation/user_guides/publishing/publishing.malloynb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,7 @@ npx @malloy-publisher/server --server_root .
The `--server_root` should point to the directory that **contains** your package folder(s), not the package itself.

```
projects/ ← Run npx from HERE (--server_root .)
my-data/ ← Run npx from HERE (--server_root .)
├── publisher.config.json ← Server configuration
└── my-analytics/ ← This is your package
├── publisher.json
Expand Down Expand Up @@ -77,7 +77,7 @@ That's it for local files. If your models use DuckDB with `.parquet`, `.csv`, or

```json
{
"projects": [
"environments": [
{
"name": "default",
"connections": [
Expand Down Expand Up @@ -166,7 +166,7 @@ services:
- ./packages:/publisher/packages
restart: unless-stopped
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:4000/status"]
test: ["CMD", "curl", "-f", "http://localhost:4000/api/v0/status"]
interval: 30s
timeout: 10s
retries: 3
Expand All @@ -192,13 +192,13 @@ Publisher reads runtime settings from environment variables. The most common one
### Health Check

```bash
curl http://localhost:4000/status
curl http://localhost:4000/api/v0/status
```

### List Projects
### List Environments

```bash
curl http://localhost:4000/api/v1/projects
curl http://localhost:4000/api/v0/environments
```

See the [REST API](rest_api.malloynb) documentation for all available endpoints.
Expand All @@ -216,13 +216,13 @@ See the [REST API](rest_api.malloynb) documentation for all available endpoints.

## State Persistence

Publisher persists configuration changes in a local DuckDB database (`publisher.db`). This means changes made via the REST API—adding projects, packages, or connections—survive server restarts.
Publisher persists configuration changes in a local DuckDB database (`publisher.db`). This means changes made via the REST API—adding environments, packages, or connections—survive server restarts.

### How It Works

1. **First start**: Publisher reads `publisher.config.json` and syncs it to `publisher.db`
2. **Subsequent starts**: Publisher loads from the database, ignoring config file changes
3. **API changes**: Adding/removing projects, packages, or connections updates the database
3. **API changes**: Adding/removing environments, packages, or connections updates the database

### Reinitializing from Config

Expand All @@ -247,7 +247,7 @@ By default, Publisher allows configuration changes via the API. To lock the conf
```json
{
"frozenConfig": true,
"projects": [...]
"environments": [...]
}
```

Expand Down
25 changes: 15 additions & 10 deletions src/documentation/user_guides/publishing/rest_api.malloynb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ The REST API lets you:

| Capability | Description |
|------------|-------------|
| **Browse models** | List projects, packages, and models available on the server |
| **Browse models** | List environments, packages, and models available on the server |
| **Get model schema** | Retrieve sources, measures, dimensions, and views defined in a model |
| **Execute queries** | Run Malloy queries and get JSON results |
| **Explore databases** | List schemas, tables, and columns from connected databases |
Expand All @@ -40,18 +40,16 @@ The REST API lets you:
Run a query against a model:

```bash
curl -X POST "http://localhost:4000/api/v0/projects/my-project/packages/ecommerce/queryResults/orders.malloy" \
curl -X POST "http://localhost:4000/api/v0/environments/my-env/packages/ecommerce/models/orders.malloy/query" \
-H "Content-Type: application/json" \
-d '{"query": "run: orders -> { aggregate: order_count, total_revenue }"}'
-d '{"query": "run: orders -> { aggregate: order_count, total_revenue }", "compactJson": true}'
```

Response:
Response — `result` is a JSON string. Parse it to get the rows. With `"compactJson": true` it's a plain array of row objects; omit it for the full Malloy result with type metadata used for rendering:

```json
{
"result": [
{ "order_count": 12345, "total_revenue": 1234567.89 }
]
"result": "[{\"order_count\":12345,\"total_revenue\":1234567.89}]"
}
```

Expand All @@ -64,11 +62,18 @@ Response:
```javascript
async function fetchMetrics() {
const response = await fetch(
'http://localhost:4000/api/v0/projects/prod/packages/analytics/queryResults/orders.malloy?query=' +
encodeURIComponent('run: orders -> { aggregate: total_revenue }')
'http://localhost:4000/api/v0/environments/prod/packages/analytics/models/orders.malloy/query',
{
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
query: 'run: orders -> { aggregate: total_revenue }',
compactJson: true,
}),
}
);
const data = await response.json();
return data.result;
return JSON.parse(data.result);
}
```

Expand Down