### Install and Run DuckDB Server with pip

Source: https://github.com/uwdata/mosaic/blob/main/docs/server/index.md

This demonstrates installing the duckdb-server package using pip and then starting the server. Ensure you have Python and pip installed.

```bash
pip install duckdb-server
duckdb-server
```

--------------------------------

### Install MotherDuck Extension

Source: https://github.com/uwdata/mosaic/blob/main/dev/notebooks/motherduck.ipynb

Installs the MotherDuck extension for DuckDB. This step is necessary to enable connectivity and interaction with MotherDuck services.

```python
# Install MotherDuck

c = duckdb.connect()
c.query("FORCE INSTALL motherduck")
```

--------------------------------

### Bias Specification Examples

Source: https://github.com/uwdata/mosaic/blob/main/docs/examples/bias.md

Demonstrates the specification for the Bias Parameter across different formats: JavaScript, YAML, and JSON. These examples show how to configure the bias parameter for data querying and visualization.

```javascript
import { Param } from "@uwdata/mosaic-core";

export const bias = Param.value(0.5);

export default {
  // ... other spec properties
  params: {
    bias: bias
  }
};
```

```yaml
params:
  bias:
    value: 0.5
```

```json
{
  "params": {
    "bias": {
      "value": 0.5
    }
  }
}
```

--------------------------------

### Run Mosaic Server with Go

Source: https://github.com/uwdata/mosaic/blob/main/packages/server/duckdb-server-go/README.md

Starts the Mosaic server using the `go run` command. The `-tags=duckdb_arrow` flag is used for specific build configurations. This command does not automatically restart the server upon code changes.

```sh
go run -tags=duckdb_arrow .
```

--------------------------------

### Overview Detail Visualization Specification (JavaScript)

Source: https://github.com/uwdata/mosaic/blob/main/docs/examples/overview-detail.md

Defines the visualization specification for the Overview + Detail example using JavaScript. This file outlines the marks, encodings, and interactions for the chart.

```javascript
import {
  intervalX,
  line,
  area,
  rule,
  rect,
  text,
  color,
  scale,
  encode,
  Legend,
  M4
} from "@uwdata/vgplot";

export default {
  preset: "M4",
  V:
    M4.group(
      { fill: "#f8f8f8" },
      M4.line({
        data: (d) => d.overview,
        x: "Year",
        y: "count",
        stroke: "overview"
      }),
      M4.area({
        data: (d) => d.overview,
        x: "Year",
        y: "count",
        fill: "overview",
        opacity: 0.2
      }),
      M4.rule({
        data: (d) => d.overview,
        y: "overview",
        stroke: "overview",
        strokeWidth: 1.5
      }),
      M4.rect({
        data: (d) => d.overview,
        y: "overview",
        width: 100,
        fill: "overview",
        opacity: 0.4
      }),
      M4.text({
        data: (d) => d.overview,
        x: "Year",
        y: "overview",
        text: "overview",
        dy: -8,
        fill: "overview"
      })
    ),
  P: [
    intervalX({
      snap: true,
      translate: "overview"
    })
  ],
  marks: [
    {
      name: "overview",
      transform: [{ type: "group", by: ["overview"] }],
      interval: "overview",
      encode: {
        update: {
          fill: { value: "transparent" },
          stroke: { value: "#aaa" },
          strokeWidth: { value: 1 }
        }
      }
    },
    line({
      data: (d) => d.overview,
      x: "Year",
      y: "count",
      stroke: "overview"
    }),
    area({
      data: (d) => d.overview,
      x: "Year",
      y: "count",
      fill: "overview",
      opacity: 0.2
    }),
    rule({
      data: (d) => d.overview,
      y: "overview",
      stroke: "overview",
      strokeWidth: 1.5
    }),
    rect({
      data: (d) => d.overview,
      y: "overview",
      width: 100,
      fill: "overview",
      opacity: 0.4
    }),
    text({
      data: (d) => d.overview,
      x: "Year",
      y: "overview",
      text: "overview",
      dy: -8,
      fill: "overview"
    })
  ]
};

```

--------------------------------

### SPLOM Specification Examples

Source: https://github.com/uwdata/mosaic/blob/main/docs/examples/splom.md

Provides examples of the Scatter Plot Matrix (SPLOM) specification in different formats: JavaScript, YAML, and JSON. These files define the structure and data mapping for generating the SPLOM visualization, enabling users to understand and customize the plot's appearance and behavior.

```javascript
import * as vg from "@uwdata/vgplot";

const data = await vg.csv("/data/iris.csv");
const xscale = vg.Scale("band");
const yscale = vg.Scale("band");

const plot = vg.Plot()
    .add(
        vg.Mark("rect", { fillOpacity: 0.6, stroke: "white" }),
        vg.X("species", { axis: null, scale: xscale }),
        vg.Y("species", { axis: null, scale: yscale }),
        vg.Color("species", { legend: null }),
        vg.DodgeX(0.5),
        vg.DodgeY(0.5),
        vg.Group("species", {x: "species", y: "species"})
    )
    .add(
        vg.Mark("text", { fontSize: 10 }),
        vg.X("species", { axis: null, scale: xscale }),
        vg.Y("species", { axis: null, scale: yscale }),
        vg.Text(d => `${d.count}`),
        vg.Group("species", {x: "species", y: "species"})
    )
    .add(
        vg.Mark("point", { opacity: 0.7, filled: true, size: 3 }),
        vg.X("petalLength", { scale: vg.Scale("linear", { domain: [0, 8] }) }),
        vg.Y("petalWidth", { scale: vg.Scale("linear", { domain: [0, 3] }) }),
        vg.Color("species", { legend: null }),
        vg.Tooltip(["species", "petalLength", "petalWidth"])
    )
    .grid(true)
    .margins(10)
    .width(500)
    .height(500)
    .data(data);

plot.mount("#plot");

```

```yaml
title: "Scatter Plot Matrix"

data: !csv "/data/iris.csv"

marks:
  - rect:
      fillOpacity: 0.6
      stroke: "white"
    x: "species"
    y: "species"
    color: "species"
    dodgeX: 0.5
    dodgeY: 0.5
    group: ["species", "species"]
  - text:
      fontSize: 10
    x: "species"
    y: "species"
    text: "count"
    group: ["species", "species"]
  - point:
      opacity: 0.7
      filled: true
      size: 3
    x: "petalLength"
    y: "petalWidth"
    color: "species"
    tooltip: ["species", "petalLength", "petalWidth"]

scales:
  x: !band
  y: !band
  color: !ordinal
  x_linear: !linear
    domain: [0, 8]
  y_linear: !linear
    domain: [0, 3]

projection: "identity"

width: 500
height: 500

grid: true
margins: 10

```

```json
{
  "title": "Scatter Plot Matrix",
  "data": {
    "url": "/data/iris.csv",
    "format": {"type": "csv"}
  },
  "marks": [
    {
      "type": "rect",
      "properties": {
        "enter": {
          "fillOpacity": {"value": 0.6},
          "stroke": {"value": "white"}
        }
      },
      "transform": [
        {"type": "group", "by": "datum.species"}
      ],
      "encode": {
        "update": {
          "x": {"field": "species", "scale": "xscale"},
          "y": {"field": "species", "scale": "yscale"},
          "tooltip": {"signal": "datum"}
        }
      }
    },
    {
      "type": "text",
      "properties": {
        "enter": {"fontSize": {"value": 10}}
      },
      "transform": [
        {"type": "group", "by": "datum.species"}
      ],
      "encode": {
        "update": {
          "x": {"field": "species", "scale": "xscale"},
          "y": {"field": "species", "scale": "yscale"},
          "text": {"field": "count"}
        }
      }
    },
    {
      "type": "symbol",
      "properties": {
        "enter": {"opacity": {"value": 0.7}, "filled": {"value": true}, "size": {"value": 3}}
      },
      "encode": {
        "update": {
          "x": {"field": "petalLength", "scale": "xscale_linear"},
          "y": {"field": "petalWidth", "scale": "yscale_linear"},
          "fill": {"field": "species", "scale": "color"},
          "tooltip": {"signal": "datum"}
        }
      }
    }
  ],
  "scales": [
    {"name": "xscale", "type": "band", "padding": 0.5},
    {"name": "yscale", "type": "band", "padding": 0.5},
    {"name": "color", "type": "ordinal", "domain": {"data": "data", "field": "species"}},
    {"name": "xscale_linear", "type": "linear", "domain": [0, 8]},
    {"name": "yscale_linear", "type": "linear", "domain": [0, 3]}
  ],
  "width": 500,
  "height": 500,
  "grid": true,
  "margins": 10
}

```

--------------------------------

### Load and Render Mosaic Specification (JavaScript)

Source: https://github.com/uwdata/mosaic/blob/main/dev/index.html

The `load` function fetches a YAML specification, parses it, and then renders it either as a DOM element or an ESM module. It handles different loading scenarios, including examples from query strings and local development paths. The function depends on `yaml.parse`, `parseSpec`, `astToDOM`, and `astToESM` for processing the visualization.

```javascript
async function load(name, source) {
  view.replaceChildren();
  let dir = '../specs/yaml';
  if (name === 'none' && location.search) {
    // get example name from query string
    name = location.search.slice(1);
    if (name.startsWith('dev:')) {
      // route to local spec for testing / exploration
      name = name.slice(4);
      dir = './specs';
    }
  }
  if (name !== 'none') {
    const spec = yaml.parse(
      await fetch(`${dir}/${name}.yaml`).then(res => res.text())
    );
    // options for output generation
    const baseURL = location.origin + '/';
    const options = connectorMenu.value === 'wasm' ? { baseURL } : {};
    // parse and load spec
    const ast = parseSpec(spec);
    const el = await (source === 'esm' ? loadESM : loadDOM)(ast, options);
    view.replaceChildren(el);
  }
}
```

--------------------------------

### Overview Detail Visualization Specification (JSON)

Source: https://github.com/uwdata/mosaic/blob/main/docs/examples/overview-detail.md

Defines the visualization specification for the Overview + Detail example using JSON. This machine-readable format is often used for data exchange and configuration.

```json
{
  "preset": "M4",
  "V": [
    {
      "group": {
        "fill": "#f8f8f8"
      },
      "V": [
        {
          "line": {
            "data": "(d) => d.overview",
            "x": "Year",
            "y": "count",
            "stroke": "overview"
          }
        },
        {
          "area": {
            "data": "(d) => d.overview",
            "x": "Year",
            "y": "count",
            "fill": "overview",
            "opacity": 0.2
          }
        },
        {
          "rule": {
            "data": "(d) => d.overview",
            "y": "overview",
            "stroke": "overview",
            "strokeWidth": 1.5
          }
        },
        {
          "rect": {
            "data": "(d) => d.overview",
            "y": "overview",
            "width": 100,
            "fill": "overview",
            "opacity": 0.4
          }
        },
        {
          "text": {
            "data": "(d) => d.overview",
            "x": "Year",
            "y": "overview",
            "text": "overview",
            "dy": -8,
            "fill": "overview"
          }
        }
      ]
    }
  ],
  "P": [
    {
      "intervalX": {
        "snap": true,
        "translate": "overview"
      }
    }
  ],
  "marks": [
    {
      "name": "overview",
      "transform": [
        {
          "type": "group",
          "by": ["overview"]
        }
      ],
      "interval": "overview",
      "encode": {
        "update": {
          "fill": {
            "value": "transparent"
          },
          "stroke": {
            "value": "#aaa"
          },
          "strokeWidth": {
            "value": 1
          }
        }
      }
    },
    {
      "line": {
        "data": "(d) => d.overview",
        "x": "Year",
        "y": "count",
        "stroke": "overview"
      }
    },
    {
      "area": {
        "data": "(d) => d.overview",
        "x": "Year",
        "y": "count",
        "fill": "overview",
        "opacity": 0.2
      }
    },
    {
      "rule": {
        "data": "(d) => d.overview",
        "y": "overview",
        "stroke": "overview",
        "strokeWidth": 1.5
      }
    },
    {
      "rect": {
        "data": "(d) => d.overview",
        "y": "overview",
        "width": 100,
        "fill": "overview",
        "opacity": 0.4
      }
    },
    {
      "text": {
        "data": "(d) => d.overview",
        "x": "Year",
        "y": "overview",
        "text": "overview",
        "dy": -8,
        "fill": "overview"
      }
    }
  ]
}

```

--------------------------------

### Overview Detail Visualization Specification (YAML)

Source: https://github.com/uwdata/mosaic/blob/main/docs/examples/overview-detail.md

Defines the visualization specification for the Overview + Detail example using YAML. This format provides a declarative way to describe the chart's components and behavior.

```yaml
preset: M4
V:
  - group:
      fill: "#f8f8f8"
    V:
      - line:
          data: (d) => d.overview
          x: "Year"
          y: "count"
          stroke: "overview"
      - area:
          data: (d) => d.overview
          x: "Year"
          y: "count"
          fill: "overview"
          opacity: 0.2
      - rule:
          data: (d) => d.overview
          y: "overview"
          stroke: "overview"
          strokeWidth: 1.5
      - rect:
          data: (d) => d.overview
          y: "overview"
          width: 100
          fill: "overview"
          opacity: 0.4
      - text:
          data: (d) => d.overview
          x: "Year"
          y: "overview"
          text: "overview"
          dy: -8
          fill: "overview"
P:
  - intervalX:
      snap: true
      translate: "overview"
marks:
  - name: "overview"
    transform:
      - type: "group"
        by: ["overview"]
    interval: "overview"
    encode:
      update:
        fill: { value: "transparent" }
        stroke: { value: "#aaa" }
        strokeWidth: { value: 1 }
  - line:
      data: (d) => d.overview
      x: "Year"
      y: "count"
      stroke: "overview"
  - area:
      data: (d) => d.overview
      x: "Year"
      y: "count"
      fill: "overview"
      opacity: 0.2
  - rule:
      data: (d) => d.overview
      y: "overview"
      stroke: "overview"
      strokeWidth: 1.5
  - rect:
      data: (d) => d.overview
      y: "overview"
      width: 100
      fill: "overview"
      opacity: 0.4
  - text:
      data: (d) => d.overview
      x: "Year"
      y: "overview"
      text: "overview"
      dy: -8
      fill: "overview"

```

--------------------------------

### loadExtension

Source: https://github.com/uwdata/mosaic/blob/main/docs/api/sql/data-loading.md

Generates a query to install and load a named DuckDB extension.

```APIDOC
## loadExtension

### Description
Generates a query to install and load a named DuckDB extension.

### Method
Not applicable (generates SQL query)

### Endpoint
Not applicable

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
`loadExtension("spatial")`

### Response
#### Success Response (200)
SQL query string to install and load the extension.

#### Response Example
```sql
-- Example for loadExtension("spatial")
INSTALL spatial;
LOAD spatial;
```
```

--------------------------------

### Query Building Overview

Source: https://github.com/uwdata/mosaic/blob/main/docs/api/sql/queries.md

This example demonstrates how to build a basic aggregation query using the Mosaic SQL query builder. It selects a column, counts records, sums values, filters by a condition, and groups the results.

```APIDOC
## Query Building Overview

### Description
Demonstrates building a basic aggregation query with `SELECT`, `FROM`, `GROUP BY`, and `WHERE` clauses.

### Method
N/A (Illustrative Code)

### Endpoint
N/A

### Parameters
N/A

### Request Example
```javascript
import { Query, count, gt, sum } from "@uwdata/mosaic-sql";

// SELECT "category", count() AS "count", sum("value") AS "value"
//   FROM "table" WHERE "value" > 0 GROUP BY "category"
const sqlQuery = Query
  .from("table")
  .select("category", { count: count(), sum: sum("value") })
  .groupby("category")
  .where(gt("value", 0));

console.log(sqlQuery.toString()); // Outputs the SQL string
```

### Response
#### Success Response (200)
N/A (This is a code generation example, not an API endpoint)

#### Response Example
```sql
SELECT "category", count() AS "count", sum("value") AS "value" FROM "table" WHERE "value" > 0 GROUP BY "category"
```
```

--------------------------------

### Update Mosaic Project Dependencies with Go

Source: https://github.com/uwdata/mosaic/blob/main/packages/server/duckdb-server-go/README.md

Updates project dependencies to their latest versions using `go get -u`. After updating, `go mod tidy` is run to clean up the `go.mod` file, ensuring it accurately reflects the project's dependencies.

```sh
go get -u
go mod tidy
```

--------------------------------

### Connect to MySQL with Mosaic

Source: https://github.com/uwdata/mosaic/blob/main/docs/api/core/multi-database-support.md

This example shows how to connect to a MySQL database using Mosaic and DuckDB. It outlines the process of defining database connection parameters, creating a connection string, attaching the MySQL database with the ATTACH command, and then proceeding to load data and build visualizations. Remember to substitute the placeholder configuration values with your actual MySQL credentials.

```javascript
import * as vg from "@uwdata/vgplot";

// database configuration info
// replace values with your specific configuration
const config = {
  database: "YOUR_DATABASE_NAME",
  user: "root",
  password: "YOUR_PASSWORD",
  host: "YOUR_HOST_IP",
  port: "YOUR_PORT"
};

// map configuration info to a connection string
const mysql_connection_string = Object.entries(config)
  .map(([key, value]) => `${key}=${value}`)
  .join(" ");

await vg.coordinator().exec([
  // attach and use a MySQL database
  `ATTACH '${mysql_connection_string}' AS mysqldb (TYPE MYSQL)`,
  "USE mysqldb",
  vg.loadParquet("ca55", "data/ca55-south.parquet") // load a dataset
]);

// now add Mosaic specification code as usual!

```

--------------------------------

### Reload Mosaic View with Selected Specification (JavaScript)

Source: https://github.com/uwdata/mosaic/blob/main/dev/index.html

The `reload` function is responsible for updating the Mosaic visualization when the user selects a new example or source. It calls the `load` function with the chosen example name and source type. This is a core function for navigating and interacting with the example gallery.

```javascript
function reload() {
  load(exampleMenu.value, sourceMenu.value);
}
```

--------------------------------

### Region Interactor Specification Examples

Source: https://github.com/uwdata/mosaic/blob/main/docs/examples/region-tests.md

Provides examples of the region interactor specification in JavaScript, YAML, and JSON formats. These examples define the configuration and behavior of region interactors for visualization.

```javascript
import { region } from "@uwdata/vgplot";

export default {
  title: "Region Interactor",
  description: "A specification for a region interactor.",
  signals: [
    { name: "x", value: 0 },
    { name: "y", value: 0 }
  ],
  marks: [
    region({
      encode: {
        enter: {
          fill: { value: "steelblue" },
          opacity: { value: 0.2 }
        },
        update: {
          x: { signal: "x" },
          y: { signal: "y" },
          width: { value: 100 },
          height: { value: 100 }
        }
      }
    })
  ]
}
```

```yaml
title: "Region Interactor"
description: "A specification for a region interactor."
signals:
  - name: "x"
    value: 0
  - name: "y"
    value: 0
marks:
  - type: "region"
    encode:
      enter:
        fill: { value: "steelblue" }
        opacity: { value: 0.2 }
      update:
        x: { signal: "x" }
        y: { signal: "y" }
        width: { value: 100 }
        height: { value: 100 }
```

```json
{
  "title": "Region Interactor",
  "description": "A specification for a region interactor.",
  "signals": [
    { "name": "x", "value": 0 },
    { "name": "y", "value": 0 }
  ],
  "marks": [
    {
      "type": "region",
      "encode": {
        "enter": {
          "fill": { "value": "steelblue" },
          "opacity": { "value": 0.2 }
        },
        "update": {
          "x": { "signal": "x" },
          "y": { "signal": "y" },
          "width": { "value": 100 },
          "height": { "value": 100 }
        }
      }
    }
  ]
}
```

--------------------------------

### Format, Test, and Lint Mosaic Project with Go

Source: https://github.com/uwdata/mosaic/blob/main/packages/server/duckdb-server-go/README.md

Ensures code quality by running the Go formatter (`go fmt`), tests (`go test`), and linter (`golangci-lint`). The `-tags=duckdb_arrow` flag is applied to the test command for specific build configurations. These commands should be run before submitting a pull request.

```sh
go fmt ./...
go test -tags=duckdb_arrow ./...
golangci-lint run
```

--------------------------------

### Client Connection

Source: https://github.com/uwdata/mosaic/blob/main/docs/api/core/coordinator.md

Connect a client to the coordinator.

```APIDOC
## Connect Client

### Description
Connect a client to this coordinator. Upon connection, the client lifecycle will initiate.

### Method
`POST`

### Endpoint
`/coordinator/connect`

### Parameters
#### Request Body
- **client** (object) - Required - The client to connect.

### Request Example
```json
{
  "client": "[client_instance]"
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.

### Response Example
```json
{
  "message": "Client connected successfully."
}
```
```

--------------------------------

### Run DuckDB Server with Python

Source: https://context7.com/uwdata/mosaic/llms.txt

Provides instructions and configuration examples for running a local DuckDB server using Python. This server enables WebSocket and HTTP query support, allowing clients to interact with DuckDB databases remotely.

```bash
# Install and run with uvx
uvx duckdb-server

# Or install with pip
pip install duckdb-server
duckdb-server

# Server runs on http://localhost:3000 by default

```

--------------------------------

### Install Dependencies for Dataframe Libraries

Source: https://github.com/uwdata/mosaic/blob/main/dev/notebooks/dataframe-interop.ipynb

Installs necessary dataframe libraries that are not core dependencies of Mosaic. This ensures all required libraries are available for testing interoperability.

```python
# Install dataframe libs not part of Mosaic dependencies
!uv pip install dask ibis-framework pyarrow-hotfix modin polars -q
```

--------------------------------

### DuckDB Go Server Command-Line Options

Source: https://github.com/uwdata/mosaic/blob/main/packages/server/duckdb-server-go/README.md

Customizable flags to control the behavior of the DuckDB Go Server.

```APIDOC
## DuckDB Go Server Command-Line Options

You can customize the server behavior with the following command-line flags:

- `--database <path>`: Path to a DuckDB database file (e.g., "database.db"). Defaults to an in-memory database.
- `--address <address>`: The HTTP address to listen on. Defaults to "localhost".
- `--port <port>`: The HTTP port to listen on. Defaults to "3000".
- `--connection-pool-size <size>`: The maximum size of the connection pool. Defaults to 10.
- `--max-cache-entries <size>`: The maximum number of cache entries. Defaults to 1000.
- `--max-cache-bytes <bytes>`: Max number of cache size in bytes (overrides max-cache-entries if both are set). Defaults to 0 (no limit).
- `--cache-ttl <duration>`: Time-to-live for cache entries as a Go duration. 0s means no expiration (e.g., '10m', '1h'). Defaults to 0s.
- `--cert <path>`: Path to a TLS certificate file to enable HTTPS.
- `--key <path>`: Path to a TLS private key file to enable HTTPS.
- `--schema-match-headers`: Comma-separated list of headers to match against schema names for multi-tenant access control (e.g., `X-Tenant-Id,verified-user-id`).
- `--load-extensions`: Comma-separated list of extensions to install and load at startup. Use a pipe after the extension name to specify the repository. Unspecified repositories will default to 'core'. (e.g. `mysql_scanner,netquack|community,aws|core_nightly`
- `--function-blocklist`: Comma-separated list of functions to block, useful for blocking functions that may pose security or performance risks. (e.g., 'bigquery_query,read_parquet')
```

--------------------------------

### DuckDB Server API Endpoints

Source: https://github.com/uwdata/mosaic/blob/main/packages/server/duckdb-server-rust/Readme.md

The DuckDB server supports queries via HTTP GET and POST, and WebSockets. The GET endpoint is useful for debugging. Each endpoint takes a JSON object with a command in the 'type' field.

```APIDOC
## DuckDB Server API

### Description
The DuckDB server supports queries via HTTP GET and POST, and WebSockets. The GET endpoint is useful for debugging. For example, you can query it with [this url](<http://localhost:3000/?query={"sql":"select 1","type":"json"}>). Each endpoint takes a JSON object with a command in the `type` field. The server supports the following commands:

* `exec`: Executes the SQL query in the `sql` field.
* `arrow`: Executes the SQL query in the `sql` field and returns the result in Apache Arrow format.
* `json`: Executes the SQL query in the `sql` field and returns the result in JSON format.

### Methods
GET, POST, WebSockets

### Endpoints
/

### Request Body (for POST)

```json
{
  "sql": "string",
  "type": "exec" | "arrow" | "json"
}
```

### Request Example (GET)

```
http://localhost:3000/?query={"sql":"select 1","type":"json"}
```

### Request Example (POST)

```json
{
  "sql": "SELECT * FROM my_table",
  "type": "json"
}
```

### Response

#### Success Response (200)

- **data** (any) - The query results in the requested format (JSON or Apache Arrow).

#### Response Example (JSON)

```json
{
  "data": [
    {"column1": "value1", "column2": "value2"}
  ]
}
```

#### Response Example (Arrow)

[Binary data in Apache Arrow format]
```

--------------------------------

### Run DuckDB Server with pipx

Source: https://github.com/uwdata/mosaic/blob/main/docs/server/index.md

This command directly runs the DuckDB server using pipx, a tool for installing and running Python applications in isolated environments. It requires pipx to be installed.

```bash
pipx run duckdb-server
```

--------------------------------

### Configure DuckDB Server Python Application

Source: https://context7.com/uwdata/mosaic/llms.txt

A configuration example for the DuckDB server application created with `create_app` from the `duckdb_server` Python library. This allows customization of server host, port, CORS, and SSL settings.

```python
# duckdb_server/server.py configuration example
from duckdb_server import create_app

app = create_app({
    'host': 'localhost',
    'port': 3000,
    'cors': True,
    'ssl': False
})

if __name__ == '__main__':
    app.run()

```

--------------------------------

### Logger Management

Source: https://github.com/uwdata/mosaic/blob/main/docs/api/core/coordinator.md

Get or set the coordinator's logger.

```APIDOC
## Logger Management

### Description
Get or set the coordinator's logger. The logger defaults to the standard JavaScript `console`. A logger instance must support `log`, `info`, `warn`, and `error` methods. If set to `null`, logging will be suppressed.

### Method
`GET` or `PUT`

### Endpoint
`/coordinator/logger`

### Parameters
#### PUT Request Body (Optional)
- **logger** (object | null) - The logger instance to set, or `null` to suppress logging.

### Response
#### Success Response (200)
- **logger** (object) - The current logger instance.

### Response Example (GET)
```json
{
  "logger": "[current_logger_instance]"
}
```

### Response Example (PUT)
```json
{
  "message": "Logger updated successfully."
}
```
```

--------------------------------

### Database Connector Management

Source: https://github.com/uwdata/mosaic/blob/main/docs/api/core/coordinator.md

Get or set the database connector used by the coordinator.

```APIDOC
## Database Connector

### Description
Get or set the connector used by the coordinator to issue queries to a backing data source.

### Method
`GET` or `PUT`

### Endpoint
`/coordinator/databaseConnector`

### Parameters
#### PUT Request Body (Optional)
- **connector** (object) - The database connector to set.

### Response
#### Success Response (200)
- **connector** (object) - The current database connector.

### Response Example (GET)
```json
{
  "connector": "[current_connector]"
}
```

### Response Example (PUT)
```json
{
  "message": "Database connector updated successfully."
}
```
```

--------------------------------

### Update Client using Coordinator

Source: https://github.com/uwdata/mosaic/blob/main/docs/api/core/coordinator.md

Initiates an update for a client with a specific query and priority. It returns a Promise that resolves upon query completion, invoking `client.queryPending()`, and subsequently `client.queryResult()` or `client.queryError()`. This method is intended for internal use only.

```javascript
coordinator.updateClient(client, query, priority)
```

--------------------------------

### Density 2D Plot Specification - JavaScript, YAML, JSON

Source: https://github.com/uwdata/mosaic/blob/main/docs/examples/density2d.md

These code examples provide the specification for the Density 2D plot. The JavaScript version likely configures the plot's behavior and data binding, while the YAML and JSON versions define the plot's static structure and visual encoding. These are essential for rendering the plot.

```javascript
import * as Plot from "@plot-dot-dev/plot";
import * as d3 from "d3";

const density = await d3.csv("https://raw.githubusercontent.com/uwdata/mosaic/main/data/movies.csv", d3.autoType);

const colorDomain = d3.ticks(0, 1, 3);

const bandwidth = 0.1;

return Plot.plot({
  marks: [
    Plot.density(
      density,
      {
        x: "IMDB_Rating",
        y: "Rotten_Tomatoes_Rating",
        fill: "Source",
        bandwidth: bandwidth
      }
    ),
    Plot.axis("x", { tickFormat: ".1f" }),
    Plot.axis("y", { tickFormat: ".1f" })
  ]
});
```

```yaml
type: plot
marks: [
  {
    type: density,
    x: "IMDB_Rating",
    y: "Rotten_Tomatoes_Rating",
    fill: "Source",
    bandwidth: 0.1
  },
  {
    type: axis,
    grid: true,
    x: {
      tickFormat: ".1f"
    }
  },
  {
    type: axis,
    y: {
      tickFormat: ".1f"
    }
  }
]

```

```json
{
  "type": "plot",
  "marks": [
    {
      "type": "density",
      "x": "IMDB_Rating",
      "y": "Rotten_Tomatoes_Rating",
      "fill": "Source",
      "bandwidth": 0.1
    },
    {
      "type": "axis",
      "grid": true,
      "x": {
        "tickFormat": ".1f"
      }
    },
    {
      "type": "axis",
      "y": {
        "tickFormat": ".1f"
      }
    }
  ]
}

```

--------------------------------

### Initialize Mosaic View and Event Listeners (JavaScript)

Source: https://github.com/uwdata/mosaic/blob/main/dev/index.html

This snippet initializes the Mosaic visualization environment by selecting DOM elements for the view, menus, and toggles. It sets up event listeners for user interactions on these elements to control data loading, connector selection, and query behavior. Dependencies include the 'yaml' library for parsing specifications and functions from './setup.ts' for core Mosaic functionality.

```javascript
import yaml from '../node_modules/yaml/browser/index.js';
import { astToDOM, astToESM, clear, parseSpec, setDatabaseConnector, vg } from './setup.ts';

const view = document.querySelector('#view');
const connectorMenu = document.querySelector('#connectors');
const exampleMenu = document.querySelector('#examples');
const sourceMenu = document.querySelector('#source');
const qlogToggle = document.querySelector('#query-log');
const cacheToggle = document.querySelector('#cache');
const consolidateToggle = document.querySelector('#consolidate');
const preaggToggle = document.querySelector('#preagg');
const preaggState = document.querySelector('#preagg-state');

connectorMenu.addEventListener('change', setConnector);
exampleMenu.addEventListener('change', reload);
sourceMenu.addEventListener('change', reload);
qlogToggle.addEventListener('input', setQueryLog);
cacheToggle.addEventListener('input', setCache);
consolidateToggle.addEventListener('input', setConsolidate);
preaggToggle.addEventListener('input', setPreAggregate);
```

--------------------------------

### Query.offset()

Source: https://github.com/uwdata/mosaic/blob/main/docs/api/sql/queries.md

Offsets the starting point of the query results. This is used in conjunction with `limit` for pagination.

```APIDOC
## Query.offset()

### Description
Update the query to offset the results by the specified number of _rows_ and return this query instance.

### Method
`Query.offset(rows)`

### Parameters
#### Query Parameters
- **rows** (number) - Required - The number of rows to skip from the beginning of the result set.

### Request Example
```json
{
  "rows": 20
}
```

### Response
#### Success Response (200)
- **QueryInstance** (object): The updated query instance with an OFFSET clause added.
```

--------------------------------

### Coordinator Instance

Source: https://github.com/uwdata/mosaic/blob/main/docs/api/core/coordinator.md

Retrieves the default global coordinator instance.

```APIDOC
## Get Global Coordinator

### Description
Get the default global coordinator instance.

### Method
`GET`

### Endpoint
`/coordinator`

### Parameters
None

### Response
#### Success Response (200)
- **coordinator** (object) - The default global coordinator instance.

### Response Example
```json
{
  "coordinator": "[coordinator_instance]"
}
```
```

--------------------------------

### MosaicClient update() Method

Source: https://github.com/uwdata/mosaic/blob/main/docs/api/core/client.md

Requests that the client update, for example to re-render an interface component. Called by the coordinator after queryResult. The base class does nothing.

```APIDOC
## update

### Description
Requests that a client update using its current data, for example to (re-)render an interface component, and returns the current client instance. Called by the [coordinator](./coordinator) after returning data via the [`queryResult`](#queryresult) method.

The `MosaicClient` base class does nothing here. Subclasses should override this method as needed.

### Method
`client.update()`

### Endpoint
N/A (Method call)

### Parameters
None

### Request Example
```javascript
client.update();
```

### Response
#### Success Response (200)
- **client** (MosaicClient) - The current client instance.

#### Response Example
`[Client Instance]`
```

--------------------------------

### API Endpoints

Source: https://github.com/uwdata/mosaic/blob/main/packages/server/duckdb-server-go/README.md

The server supports queries via HTTP GET and POST, and WebSockets. Each endpoint takes a JSON object with a command in the `type` field.

```APIDOC
## API Endpoints

The server supports queries via HTTP GET and POST, and WebSockets. The GET endpoint is useful for debugging. For example, you can query it with [this url](<http://localhost:3000/?query={"sql":"select 1","type":"json"}>).

Each endpoint takes a JSON object with a command in the `type`. The server supports the following commands.

### `exec`

Executes the SQL query in the `sql` field.

### `arrow`

Executes the SQL query in the `sql` field and returns the result in Apache Arrow format.

### `json`

Executes the SQL query in the `sql` field and returns the result in JSON format.
```

--------------------------------

### Coordinator Constructor

Source: https://github.com/uwdata/mosaic/blob/main/docs/api/core/coordinator.md

Creates a new Mosaic Coordinator instance.

```APIDOC
## New Coordinator

### Description
Create a new Mosaic Coordinator to manage all database communication for clients and handle selection updates.

### Method
`POST`

### Endpoint
`/coordinator`

### Parameters
#### Request Body
- **connector** (object) - Required - The database connector to use.
- **options** (object) - Optional - Configuration options for the coordinator:
  - **logger** (object) - Optional - The logger to use (defaults to `console`). Must support `log`, `info`, `warn`, and `error` methods.
  - **cache** (boolean) - Optional - Enable/disable query caching (defaults to `true`).
  - **consolidate** (boolean) - Optional - Enable/disable query consolidation (defaults to `true`).
  - **preagg** (object) - Optional - Pre-aggregation options object:
    - **enabled** (boolean) - Optional - Enable pre-aggregation optimizations (defaults to `true`).
    - **schema** (string) - Optional - The database schema for materialized views (defaults to `'mosaic'`).

### Request Example
```json
{
  "connector": "[database_connector]",
  "options": {
    "cache": true,
    "consolidate": false,
    "preagg": {
      "enabled": true,
      "schema": "my_schema"
    }
  }
}
```

### Response
#### Success Response (200)
- **coordinator** (object) - The newly created Coordinator instance.

### Response Example
```json
{
  "coordinator": "[new_coordinator_instance]"
}
```
```

--------------------------------

### Load DuckDB Extension

Source: https://github.com/uwdata/mosaic/blob/main/docs/api/sql/data-loading.md

Generates a query to install and load a named DuckDB extension. This is useful for enabling specific functionalities within DuckDB.

```javascript
loadExtension("spatial");
```

--------------------------------

### Selection Instance Methods

Source: https://github.com/uwdata/mosaic/blob/main/docs/api/core/selection.md

Methods for manipulating and querying individual Selection instances.

```APIDOC
## clone

`selection.clone()`

### Description
Create a cloned copy of this Selection instance.

### Method
Instance method of Selection

### Parameters
None

### Request Example
`const clonedSelection = mySelection.clone();`

### Response
#### Success Response (200)
- **Selection** - A deep copy of the original Selection instance.

#### Response Example
```json
{
  "cloned_selection_instance": "<Selection object>"
}
```

---

## remove

`selection.remove(source)`

### Description
Create a clone of this Selection with clauses corresponding to the provided `source` removed.

### Method
Instance method of Selection

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **source** (any) - The source of the clauses to remove.

### Request Example
`const newSelection = mySelection.remove(sourceToRemove);`

### Response
#### Success Response (200)
- **Selection** - A new Selection instance with specified clauses removed.

#### Response Example
```json
{
  "new_selection_instance": "<Selection object>"
}
```
```

--------------------------------

### Configure DuckDB WASM Connector (JavaScript)

Source: https://github.com/uwdata/mosaic/blob/main/docs/examples/index.md

Configures Mosaic to use the DuckDB-WASM connector in the browser. This is essential for running visualizations that rely on DuckDB in a client-side environment.

```javascript
import { coordinator, wasmConnector } from "@uwdata/vgplot";

coordinator().databaseConnector(wasmConnector());

```

--------------------------------

### Create Selections with Different Resolution Strategies

Source: https://github.com/uwdata/mosaic/blob/main/docs/core/index.md

Shows how to instantiate Selections with various resolution strategies: 'single', 'union', and 'intersect'. Selections are specialized params managing predicates for data filtering, and these strategies determine how multiple clauses are merged.

```javascript
import { Selection } from "@uwdata/mosaic-core";

// Create a Selection with "single" resolution strategy
Selection.single()

// Create a Selection with "union" resolution strategy
Selection.union()

// Create a Selection with "intersect" resolution strategy
Selection.intersect()

// A shorthand for "intersect" with cross-filtering
Selection.crossfilter()

// A single Selection that applies cross-filtering
Selection.single({ cross: true })
```

--------------------------------

### Get Plot Attribute Value

Source: https://github.com/uwdata/mosaic/blob/main/docs/api/vgplot/plot.md

Retrieves the value of a specified attribute by its name. This method is typically called by attribute directives to access attribute configurations.

```javascript
plot.getAttribute(name)
```

--------------------------------

### Create Interactive Dropdown for Specs (Python)

Source: https://github.com/uwdata/mosaic/blob/main/dev/notebooks/specs.ipynb

Sets up an interactive dropdown widget using `ipywidgets`. The dropdown's options are populated by the `get_specs` function, allowing users to select different example specifications. It also defines callback functions `on_change` and `open_spec` to handle user selections and update the Mosaic widget. Inputs are the `get_specs` output and a default `weather` spec. Outputs are the interactive dropdown and the updated mosaic visualization.

```python
weather = Path("specs/json/weather.json")

dropdown = widgets.Dropdown(
    options=get_specs("specs/json"),
    value=weather,
    description="Example:",
)

def on_change(change):
    open_spec(change["new"])

def open_spec(spec):
    mosaic.spec = json.loads(spec.read_text())

dropdown.observe(on_change, "value")

open_spec(weather)
```

--------------------------------

### Connector Interface

Source: https://github.com/uwdata/mosaic/blob/main/docs/api/core/connectors.md

Explains the general interface for database connectors, focusing on the `query` method and its parameters.

```APIDOC
## Connector Interface

### Description
Database connectors issue query requests to a backing data source. A connector instance should expose a `query(query)` method that returns a Promise.

### Method
- `query(query)`

### Parameters
- **query** (object) - The query to evaluate. May include:
  - _sql_: The SQL query to evaluate.
  - _type_: The query format type (e.g., `"exec"`, `"arrow"`, `"json"`).
  - Additional connector-specific options.
```