### Create Get Started SQLRooms App

Source: https://sqlrooms.org/getting-started

Use npx to create a new project from the get-started SQLRooms example. Navigate into the directory, install dependencies, and start the development server.

```bash
npx giget gh:sqlrooms/examples/get-started myapp/
cd myapp
npm install
npm run dev
```

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

### Create New Project from Get Started Example

Source: https://sqlrooms.org/examples

Use this command to quickly scaffold a new project based on the SQLRooms get-started example.

```bash
npx giget gh:sqlrooms/examples/get-started my-new-app/
```

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

### Run Multi-Room Application Locally

Source: https://sqlrooms.org/examples

Install dependencies and start the development server for the multi-room application example.

```sh
pnpm install
pnpm dev
```

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

### Install and Run Cosmos Graph Example Locally

Source: https://sqlrooms.org/examples

These commands are used to install dependencies and start the development server for the Cosmos graph visualization example locally.

```bash
npm install
npm dev
```

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

### Install, Build, and Run Deck.gl Example Locally

Source: https://sqlrooms.org/examples

Commands to install dependencies, build the project, and run the deckgl example locally.

```sh
pnpm install
pnpm build
pnpm dev deckgl-example
```

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

### Run SQL Query Editor Locally

Source: https://sqlrooms.org/examples

Install dependencies and start the development server for the SQL query editor example.

```sh
npm install
npm run dev
```

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

### Create Minimal SQLRooms App

Source: https://sqlrooms.org/getting-started

Use npx to create a new project from the minimal SQLRooms example. Navigate into the directory, install dependencies, and start the development server.

```bash
npx giget gh:sqlrooms/examples/minimal my-minimal-app/
cd my-minimal-app
npm install
npm run dev
```

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

### Quick start: Initialize AI chat with SQLRooms

Source: https://sqlrooms.org/api/ai

Set up a SQLRooms store with AI chat functionality, including data sources, AI settings, and default AI instructions and tools. This example demonstrates the core setup for integrating AI features into a SQLRooms application.

```tsx
import {
  AiSettingsSliceState,
  AiSliceState,
  createAiSettingsSlice,
  createAiSlice,
  createDefaultAiInstructions,
  createDefaultAiTools,
} from '@sqlrooms/ai';
import {
  createRoomShellSlice,
  createRoomStore,
  RoomShellSliceState,
} from '@sqlrooms/room-shell';

type RoomState = RoomShellSliceState & AiSliceState & AiSettingsSliceState;

export const {roomStore, useRoomStore} = createRoomStore<RoomState>(
  (set, get, store) => ({
    ...createRoomShellSlice({
      config: {
        dataSources: [
          {
            type: 'url',
            tableName: 'earthquakes',
            url: 'https://huggingface.co/datasets/sqlrooms/earthquakes/resolve/main/earthquakes.parquet',
          },
        ],
      },
    })(set, get, store),

    ...createAiSettingsSlice()(set, get, store),

    ...createAiSlice({
      tools: {
        ...createDefaultAiTools(store),
      },
      getInstructions: () => createDefaultAiInstructions(store),
    })(set, get, store),
  }),
);

```

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

### Quick start: Initialize Room Store with Kepler

Source: https://sqlrooms.org/api/kepler

Set up the Room store by combining room shell and Kepler slices, configuring data sources, and initializing Kepler state. This example demonstrates how to add an earthquake dataset to the map.

```tsx
import {useEffect} from 'react';
import {
  createKeplerSlice,
  KeplerMapContainer,
  KeplerSliceState,
} from '@sqlrooms/kepler';
import {
  createRoomShellSlice,
  createRoomStore,
  RoomShell,
  RoomShellSliceState,
} from '@sqlrooms/room-shell';

type RoomState = RoomShellSliceState & KeplerSliceState;

export const {roomStore, useRoomStore} = createRoomStore<RoomState>(
  (set, get, store) => ({
    ...createRoomShellSlice({
      config: {
        dataSources: [
          {
            type: 'url',
            tableName: 'earthquakes',
            url: 'https://huggingface.co/datasets/sqlrooms/earthquakes/resolve/main/earthquakes.parquet',
          },
        ],
      },
    })(set, get, store),
    ...createKeplerSlice()(set, get, store),
  }),
);

function MapPanel() {
  const mapId = useRoomStore((state) => state.kepler.config.maps[0]?.id);
  const addTableToMap = useRoomStore((state) => state.kepler.addTableToMap);
  const isTableReady = useRoomStore((state) =>
    Boolean(state.db.findTable('earthquakes')),
  );

  useEffect(() => {
    if (!isTableReady || !mapId) return;
    void addTableToMap({
      mapId,
      tableName: 'earthquakes',
      options: {
        autoCreateLayers: true,
        centerMap: true,
      },
    });
  }, [isTableReady, mapId, addTableToMap]);

  if (!mapId) return null;

  return <KeplerMapContainer mapId={mapId} />;
}

export function App() {
  return (
    <RoomShell roomStore={roomStore} className="h-screen">
      <MapPanel />
    </RoomShell>
  );
}

```

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

### Setup Room Store with Persistence

Source: https://sqlrooms.org/api/room-config

Configure and create a room store with persistence enabled. This example demonstrates how to integrate BaseRoomConfig and LayoutConfig schemas for slice configuration persistence.

```typescript
import {BaseRoomConfig, LayoutConfig} from '@sqlrooms/room-config';
import {
  createRoomShellSlice,
  createRoomStore,
  persistSliceConfigs,
} from '@sqlrooms/room-shell';

const persistence = {
  name: 'my-room-storage',
  sliceConfigSchemas: {
    room: BaseRoomConfig,
    layout: LayoutConfig,
  },
};

const {roomStore} = createRoomStore(
  persistSliceConfigs(persistence, (set, get, store) => ({
    ...createRoomShellSlice({
      config: {
        title: 'My Room',
        dataSources: [],
      },
    })(set, get, store),
  })),
);
```

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

### Install @sqlrooms/utils

Source: https://sqlrooms.org/api/utils

Install the utility package using npm.

```bash
npm install @sqlrooms/utils
```

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

### Install @sqlrooms/layout-config

Source: https://sqlrooms.org/api/layout-config

Install the package using npm.

```bash
npm install @sqlrooms/layout-config
```

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

### Install @sqlrooms/kepler-config

Source: https://sqlrooms.org/api/kepler-config

Install the package using npm.

```bash
npm install @sqlrooms/kepler-config
```

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

### Install @sqlrooms/dropzone

Source: https://sqlrooms.org/api/dropzone

Install the package using npm or yarn.

```bash
npm install @sqlrooms/dropzone
# or
yarn add @sqlrooms/dropzone
```

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

### Create New Project from Multi-Room Example

Source: https://sqlrooms.org/examples

Use this command to scaffold a new project based on the SQLRooms multi-room example.

```bash
npx giget gh:sqlrooms/examples/multi-room my-new-app/
```

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

### Create New Project from Query Example

Source: https://sqlrooms.org/examples

Use this command to scaffold a new project based on the SQLRooms query editor example.

```bash
npx giget gh:sqlrooms/examples/query my-new-app/
```

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

### Install @sqlrooms/room-store

Source: https://sqlrooms.org/api/room-store

Install the package using npm.

```bash
npm install @sqlrooms/room-store
```

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

### Install @sqlrooms/ui

Source: https://sqlrooms.org/api/ui

Install the @sqlrooms/ui package using npm or yarn.

```bash
npm install @sqlrooms/ui
# or
yarn add @sqlrooms/ui
```

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

### Install @sqlrooms/color-scales

Source: https://sqlrooms.org/api/color-scales

Install the package using npm.

```bash
npm install @sqlrooms/color-scales
```

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

### Create AI RAG Example Project

Source: https://sqlrooms.org/examples

Use this command to quickly set up a new project for the AI RAG example.

```bash
npx giget gh:sqlrooms/examples/ai-rag my-new-app/
```

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

### Install @sqlrooms/monaco-editor

Source: https://sqlrooms.org/api/monaco-editor

Install the package using npm.

```bash
npm install @sqlrooms/monaco-editor
```

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

### Install @sqlrooms/ai-core and dependencies

Source: https://sqlrooms.org/api/ai-core

Install the core AI package along with room store, UI components, and AI libraries. Ensure @sqlrooms/ui is installed as a peer dependency for visual components.

```bash
npm install @sqlrooms/ai-core @sqlrooms/room-store @sqlrooms/ui zod ai
```

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

### Create a SQLRooms store with MotherDuck connector

Source: https://sqlrooms.org/api/motherduck

Quick start example demonstrating how to create a SQLRooms store using the MotherDuck WASM connector. Requires an MotherDuck MD token.

```tsx
import {createWasmMotherDuckDbConnector} from '@sqlrooms/motherduck';
import {
  createRoomShellSlice,
  createRoomStore,
  RoomShellSliceState,
} from '@sqlrooms/room-shell';

type RoomState = RoomShellSliceState;

export function createStore(mdToken: string) {
  return createRoomStore<RoomState>((set, get, store) => ({
    ...createRoomShellSlice({
      connector: createWasmMotherDuckDbConnector({
        mdToken,
      }),
    })(set, get, store),
  }));
}
```

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

### Install @sqlrooms/layout

Source: https://sqlrooms.org/api/layout

Install the @sqlrooms/layout package using npm.

```bash
npm install @sqlrooms/layout
```

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

### Install @sqlrooms/s3-utils

Source: https://sqlrooms.org/api/s3-utils

Install the package using npm or yarn.

```bash
npm install @sqlrooms/s3-utils
# or
yarn add @sqlrooms/s3-utils
```

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

### Install @sqlrooms/sql-editor-config

Source: https://sqlrooms.org/api/sql-editor-config

Install the package using npm.

```bash
npm install @sqlrooms/sql-editor-config
```

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

### Install @sqlrooms/duckdb

Source: https://sqlrooms.org/api/duckdb

Install the package using npm.

```bash
npm install @sqlrooms/duckdb
```

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

### Basic Chat UI Setup

Source: https://sqlrooms.org/api/ai-core

This snippet shows a basic implementation of the Chat UI component, including sessions, messages, prompt suggestions, and a composer. It's a starting point for integrating a chat interface.

```tsx
import {Chat} from '@sqlrooms/ai-core';

export function AiPanel() {
  return (
    <Chat>
      <Chat.Sessions />
      <Chat.Messages />
      <Chat.PromptSuggestions>
        <Chat.PromptSuggestions.Item text="What trends should I investigate first?" />
      </Chat.PromptSuggestions>
      <Chat.Composer placeholder="Ask a question" />
    </Chat>
  );
}
```

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

### Create New Deck.gl Discuss Project

Source: https://sqlrooms.org/examples

Use npx giget to scaffold a new project from the deckgl-discuss example repository.

```bash
npx giget gh:sqlrooms/examples/deckgl-discuss my-new-app/
```

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

### Basic MosaicSlice Setup

Source: https://sqlrooms.org/api/mosaic

Integrate MosaicSlice into your room store for managing Mosaic connections and cross-filtering. This example shows a basic setup with other common slices.

```tsx
import {createMosaicSlice, MosaicSliceState} from '@sqlrooms/mosaic';
import {createRoomStore, RoomShellSliceState} from '@sqlrooms/room-shell';
import {SqlEditorSliceState} from '@sqlrooms/sql-editor';

export type RoomState = RoomShellSliceState &
  SqlEditorSliceState &
  MosaicSliceState;

export const {roomStore, useRoomStore} = createRoomStore<RoomState>(
  (set, get, store) => ({
    // ... other slices
    ...createMosaicSlice()(set, get, store),
  }),
);
```

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

### Install SQLRooms Packages (yarn)

Source: https://sqlrooms.org/getting-started

Install the core SQLRooms packages using yarn.

```bash
yarn add @sqlrooms/room-shell @sqlrooms/duckdb @sqlrooms/ui
```

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

### Install @sqlrooms/room-config

Source: https://sqlrooms.org/api/room-config

Install the core room configuration package using npm.

```bash
npm install @sqlrooms/room-config
```

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

### Install @sqlrooms/s3-browser

Source: https://sqlrooms.org/api/s3-browser

Install the S3 browser package using npm or yarn.

```bash
npm install @sqlrooms/s3-browser
# or
yarn add @sqlrooms/s3-browser
```

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

### Create New AI Project

Source: https://sqlrooms.org/examples

Use this command to create a new project from the AI example.

```bash
npx giget gh:sqlrooms/examples/ai my-new-app/
```

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

### Install @sqlrooms/cosmos and dependencies

Source: https://sqlrooms.org/api/cosmos

Install the necessary packages for @sqlrooms/cosmos, including the room-shell and ui components.

```bash
npm install @sqlrooms/cosmos @sqlrooms/room-shell @sqlrooms/ui
```

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

### Install SQLRooms Packages (pnpm)

Source: https://sqlrooms.org/getting-started

Install the core SQLRooms packages using pnpm.

```bash
pnpm add @sqlrooms/room-shell @sqlrooms/duckdb @sqlrooms/ui
```

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

### Install @sqlrooms/recharts

Source: https://sqlrooms.org/api/recharts

Install the @sqlrooms/recharts package using npm.

```bash
npm install @sqlrooms/recharts
```

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

### Create Kepler.gl Geospatial Project

Source: https://sqlrooms.org/examples

Use this command to create a new project based on the kepler example.

```bash
npx giget gh:sqlrooms/examples/kepler my-new-app/
```

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

### Create Deck.gl + Mosaic Project

Source: https://sqlrooms.org/examples

Use this command to create a new project based on the deckgl-mosaic example.

```bash
npx giget gh:sqlrooms/examples/deckgl-mosaic my-new-app/
```

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

### Install @sqlrooms/mosaic Package

Source: https://sqlrooms.org/api/mosaic

Install the Mosaic package for SQLRooms using npm.

```bash
npm install @sqlrooms/mosaic
```

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

### Low-Level Persistence Controller Setup

Source: https://sqlrooms.org/persistence

Instantiate the persistence controller directly for fine-grained control over persistence logic, independent of Zustand. This setup includes configuring autosave, snapshot retrieval, and adapter for loading/saving.

```typescript
import {createPersistenceController} from '@sqlrooms/room-store';

const controller = createPersistenceController({
  autosaveDelayMs: 300,
  getSnapshot: () => serializeCurrentWorkspace(),
  adapter: {
    load: () => loadWorkspaceSnapshot(),
    save: (snapshot, metadata) =>
      saveWorkspaceSnapshot(snapshot, metadata?.reason),
  },
});
```

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

### After: Loading Schema Catalog with `createDbSchemaTrees`

Source: https://sqlrooms.org/upgrade-guide

Example demonstrating the updated approach using `loadSchemaCatalog` and the new `createDbSchemaTrees` signature.

```typescript
import {createDbSchemaTrees} from '@sqlrooms/duckdb-core';
import {
  defaultLoadSchemaCatalogFilter,
  loadSchemaCatalog,
} from '@sqlrooms/duckdb';

const schemas = await loadSchemaCatalog(connector, {
  filterFunction: (entry) =>
    entry.type === 'schema' && entry.schema === 'scratch'
      ? false
      : defaultLoadSchemaCatalogFilter(entry),
});
const trees = createDbSchemaTrees(schemas);
```

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

### Install @sqlrooms/data-table

Source: https://sqlrooms.org/api/data-table

Install the data table package using npm or yarn.

```bash
npm install @sqlrooms/data-table
# or
yarn add @sqlrooms/data-table
```

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

### Install @sqlrooms/room-shell

Source: https://sqlrooms.org/api/room-shell

Install the room-shell package along with its dependencies for DuckDB and UI.

```bash
npm install @sqlrooms/room-shell @sqlrooms/duckdb @sqlrooms/ui
```

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

### Install @sqlrooms/discuss and related packages

Source: https://sqlrooms.org/api/discuss

Install the discuss package along with necessary room-shell, ui, and utils packages using npm.

```bash
npm install @sqlrooms/discuss @sqlrooms/room-shell @sqlrooms/ui @sqlrooms/utils
```

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

### Install @sqlrooms/motherduck and @sqlrooms/room-shell

Source: https://sqlrooms.org/api/motherduck

Install the necessary packages for using the MotherDuck connector with SQLRooms.

```bash
npm install @sqlrooms/motherduck @sqlrooms/room-shell
```

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

### Install @sqlrooms/ai and dependencies

Source: https://sqlrooms.org/api/ai

Install the @sqlrooms/ai package along with necessary dependencies for room shell, DuckDB, and UI components.

```bash
npm install @sqlrooms/ai @sqlrooms/room-shell @sqlrooms/duckdb @sqlrooms/ui
```

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

### Install @sqlrooms/deck and related packages

Source: https://sqlrooms.org/api/deck

Install the necessary packages for deck.gl integration with SQLRooms, including DuckDB and UI components.

```bash
npm install @sqlrooms/deck @sqlrooms/duckdb @sqlrooms/ui
```

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

### Install @sqlrooms/kepler and dependencies

Source: https://sqlrooms.org/api/kepler

Install the Kepler package along with necessary dependencies for room shell, DuckDB, and UI components.

```bash
npm install @sqlrooms/kepler @sqlrooms/room-shell @sqlrooms/duckdb @sqlrooms/ui
```

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

### Install sqlrooms-rag Package

Source: https://sqlrooms.org/api/ai-rag

Install the sqlrooms-rag Python package using pip.

```bash
# Install the package
pip install sqlrooms-rag
```

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

### Install @sqlrooms/schema-tree and dependencies

Source: https://sqlrooms.org/api/schema-tree

Install the schema-tree package along with its required DuckDB and UI dependencies using npm.

```bash
npm install @sqlrooms/schema-tree @sqlrooms/duckdb @sqlrooms/ui
```

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

### Install @sqlrooms/ai-rag

Source: https://sqlrooms.org/api/ai-rag

Install the ai-rag slice along with its dependencies for DuckDB and room-store.

```bash
npm install @sqlrooms/ai-rag @sqlrooms/duckdb @sqlrooms/room-store
```

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

### Install @sqlrooms/notebook

Source: https://sqlrooms.org/api/notebook

Install the package using pnpm. This command adds the @sqlrooms/notebook package to your project dependencies.

```bash
pnpm add @sqlrooms/notebook
```

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

### Install @sqlrooms/vega Package

Source: https://sqlrooms.org/api/vega

Install the @sqlrooms/vega package along with its dependencies for DuckDB and UI components.

```bash
npm install @sqlrooms/vega @sqlrooms/duckdb @sqlrooms/ui
```

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

### Install SQL Editor and Dependencies

Source: https://sqlrooms.org/api/sql-editor

Install the SQL editor package along with necessary dependencies like room-shell, duckdb, and ui.

```bash
npm install @sqlrooms/sql-editor @sqlrooms/room-shell @sqlrooms/duckdb @sqlrooms/ui
```

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

### Create New Deck.gl Project

Source: https://sqlrooms.org/examples

Use npx giget to scaffold a new project from the deckgl example repository.

```sh
npx giget gh:sqlrooms/examples/deckgl my-new-app/
```

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

### Install SQLRooms AI Packages

Source: https://sqlrooms.org/api/ai-settings

Install the necessary SQLRooms packages for AI settings, core functionality, store management, and UI components.

```bash
npm install @sqlrooms/ai-settings @sqlrooms/ai-core @sqlrooms/room-store @sqlrooms/ui
```

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

### Create MotherDuck Cloud Query Editor Project

Source: https://sqlrooms.org/examples

Use this command to quickly set up a new project for the MotherDuck Cloud Query Editor example.

```bash
npx giget gh:sqlrooms/examples/query-motherduck my-new-app/
```

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

### Create New AI App Builder Project

Source: https://sqlrooms.org/examples

Use this command to create a new project from the AI App Builder example.

```bash
npx giget gh:sqlrooms/examples/app-builder my-new-app/
```

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

### Before: Loading Table Schemas with `createDbSchemaTrees`

Source: https://sqlrooms.org/upgrade-guide

Example of how to load table schemas and create schema trees using the previous API.

```typescript
import {createDbSchemaTrees, type DataTable} from '@sqlrooms/duckdb-core';

const tables: DataTable[] = await loadTableSchemas(connector);
const trees = createDbSchemaTrees(tables);
```

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

### Quick Start React App with Room Shell

Source: https://sqlrooms.org/api/room-shell

Set up a basic SQLRooms application using RoomShell, defining data sources and layout configuration.

```tsx
import {
  createRoomShellSlice,
  createRoomStore,
  RoomShell,
  RoomShellSliceState,
} from '@sqlrooms/room-shell';
import {DatabaseIcon} from 'lucide-react';

function DataPanel() {
  return <div className="p-2">Data panel</div>;
}

function MainPanel() {
  return <div className="p-2">Main panel</div>;
}

type RoomState = RoomShellSliceState;

export const {roomStore, useRoomStore} = createRoomStore<RoomState>(
  (set, get, store) => ({
    ...createRoomShellSlice({
      config: {
        title: 'My SQLRooms App',
        dataSources: [
          {
            type: 'url',
            tableName: 'earthquakes',
            url: 'https://huggingface.co/datasets/sqlrooms/earthquakes/resolve/main/earthquakes.parquet',
          },
        ],
      },
      layout: {
        config: {
          type: 'split',
          direction: 'row',
          children: [{type: 'panel', id: 'data', defaultSize: '28%'}, 'main'],
        },
        panels: {
          data: {
            title: 'Data',
            icon: DatabaseIcon,
            component: DataPanel,
          },
          main: {
            title: 'Main',
            icon: () => null,
            component: MainPanel,
          },
        },
      },
    })(set, get, store),
  }),
);

export function App() {
  return (
    <RoomShell roomStore={roomStore} className="h-screen">
      <RoomShell.Sidebar />
      <RoomShell.LayoutComposer />
      <RoomShell.LoadingProgress />
      <RoomShell.CommandPalette />
    </RoomShell>
  );
}

```

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

### Basic Store Setup with AI Settings

Source: https://sqlrooms.org/api/ai-settings

Configure the Redux store by combining base room slices with AI core and AI settings slices. This setup initializes AI providers, models, and parameters.

```tsx
import {AiSliceState, createAiSlice} from '@sqlrooms/ai-core';
import {
  AiSettingsSliceState,
  createAiSettingsSlice,
} from '@sqlrooms/ai-settings';
import {
  BaseRoomStoreState,
  createBaseRoomSlice,
  createRoomStore,
} from '@sqlrooms/room-store';

type State = BaseRoomStoreState & AiSliceState & AiSettingsSliceState;

export const {roomStore, useRoomStore} = createRoomStore<State>(
  (set, get, store) => ({
    ...createBaseRoomSlice()(set, get, store),
    ...createAiSettingsSlice({
      config: {
        providers: {
          openai: {
            baseUrl: 'https://api.openai.com/v1',
            apiKey: '',
            models: [{modelName: 'gpt-4.1'}],
          },
        },
        customModels: [],
        modelParameters: {
          maxSteps: 30,
          additionalInstruction: '',
        },
      },
    })(set, get, store),
    ...createAiSlice({
      getInstructions: () => 'You are a data analytics assistant.',
    })(set, get, store),
  }),
);

```

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

### Initialize S3 Client and Use Utility Functions

Source: https://sqlrooms.org/api/s3-utils

Demonstrates initializing an S3 client and using the listFilesAndDirectoriesWithPrefix and deleteS3Files functions. Ensure the S3 client is properly configured.

```tsx
import {S3Client} from '@aws-sdk/client-s3';
import {listFilesAndDirectoriesWithPrefix} from '@sqlrooms/s3-utils';

// Initialize S3 client
const s3Client = new S3Client({region: 'us-east-1'});

// List files and directories
async function listFiles() {
  const files = await listFilesAndDirectoriesWithPrefix(
    s3Client,
    'my-bucket',
    'path/to/directory',
  );
  console.log(files);
}

// Delete files with a prefix
async function deleteFiles() {
  await deleteS3Files(s3Client, 'my-bucket', 'path/to/delete');
}
```

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

### MosaicSlice Setup with Cache Database

Source: https://sqlrooms.org/api/mosaic

Configure MosaicSlice to use a specific schema for pre-aggregate cache tables. This example attaches a memory database for caching and creates the mosaic schema within it.

```tsx
const mosaicCacheDatabase = '__sqlrooms_mosaic_cache';

const connector = createWebSocketDuckDbConnector({
  initializationQuery: [
    `ATTACH IF NOT EXISTS ':memory:' AS ${mosaicCacheDatabase}`,
    `CREATE SCHEMA IF NOT EXISTS ${mosaicCacheDatabase}.mosaic`,
  ].join('; '),
});

export const {roomStore, useRoomStore} = createRoomStore<RoomState>(
  (set, get, store) => ({
    // ... db slice using connector
    ...createMosaicSlice({
      preagg: {
        schema: `${mosaicCacheDatabase}.mosaic`,
      },
    })(set, get, store),
  }),
);
```

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

### Recommended Room Store Setup with Persistence

Source: https://sqlrooms.org/persistence

This snippet demonstrates the recommended way to set up a SQLRooms store with persistence using Zustand. It involves defining slice configurations, creating persistence helpers, and initializing the room store with persistence enabled. Ensure `loadWorkspaceState` and `saveWorkspaceState` are correctly implemented.

```typescript
import {
  createPersistHelpers,
  createRoomStore,
  createRoomStorePersistence,
  persistSliceConfigs,
} from '@sqlrooms/room-store';
import {BaseRoomConfig} from '@sqlrooms/room-config';
import {LayoutConfig} from '@sqlrooms/layout-config';

const sliceConfigSchemas = {
  room: BaseRoomConfig,
  layout: LayoutConfig,
} as const;

const persistHelpers = createPersistHelpers(sliceConfigSchemas);

const persistence = createRoomStorePersistence<RoomState>({
  partialize: persistHelpers.partialize,
  autosaveDelayMs: 300,
  load: async () => loadWorkspaceState(),
  save: async (snapshot, metadata) => {
    await saveWorkspaceState(snapshot, metadata?.reason);
  },
});

export const {roomStore, useRoomStore} = createRoomStore<RoomState>(
  persistSliceConfigs<RoomState, typeof sliceConfigSchemas>(
    {
      name: 'workspace-state',
      sliceConfigSchemas,
      storage: persistence.storage,
      partialize: persistence.partialize,
      merge: persistHelpers.merge,
      onRehydrateStorage: persistence.onRehydrateStorage,
    },
    (set, get, store) => ({
      // Compose room slices here.
    }),
  ),
);

```

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

### Enable PWA Support with Vite Plugin

Source: https://sqlrooms.org/offline-use

Configure Vite to enable Progressive Web App (PWA) support using vite-plugin-pwa. This example sets up automatic updates and defines basic PWA manifest properties like name, start URL, and icons.

```typescript
import {VitePWA} from 'vite-plugin-pwa';

export default defineConfig({
  plugins: [
    VitePWA({
      registerType: 'autoUpdate',
      manifest: {
        name: 'SQLRooms Query Workbench',
        short_name: 'SQLRooms',
        start_url: '.',
        display: 'standalone',
        background_color: '#ffffff',
        description: 'Query Workbench example for SQLRooms',
        icons: [
          {src: 'icon.png', sizes: '192x192', type: 'image/png'},
          {src: 'icon.png', sizes: '512x512', type: 'image/png'},
        ],
      },
    }),
  ],
});

```

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

### Install Tailwind CSS (yarn)

Source: https://sqlrooms.org/getting-started

Install Tailwind CSS version 4 using yarn.

```bash
yarn add -D tailwindcss@4
```

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

### Install Tailwind CSS (pnpm)

Source: https://sqlrooms.org/getting-started

Install Tailwind CSS version 4 using pnpm.

```bash
pnpm add -D tailwindcss@4
```

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

### Install Tailwind CSS (npm)

Source: https://sqlrooms.org/getting-started

Install Tailwind CSS version 4 using npm.

```bash
npm install -D tailwindcss@4
```

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

### Create New Cosmos Graph Project

Source: https://sqlrooms.org/examples

Use this command to create a new project from the Cosmos graph example. This sets up a new application with the necessary structure and dependencies.

```bash
npx giget gh:sqlrooms/examples/cosmos my-new-app/
```

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

### Set up AI Store Slice with Tools

Source: https://sqlrooms.org/api/ai-core

Configure the AI slice for core mode, defining tools, instructions, and optional tool renderers. This example demonstrates an 'echo' tool for echoing text back.

```tsx
import {
  createAiSlice,
  type AiSliceState,
  type ToolRendererRegistry,
} from '@sqlrooms/ai-core';
import {
  BaseRoomStoreState,
  createBaseRoomSlice,
  createRoomStore,
} from '@sqlrooms/room-store';
import {tool} from 'ai';
import {z} from 'zod';

const EchoResult = ({ 
  output,
}: { 
  output: {success: boolean; text: string} | undefined;
}) => <div>{output?.text}</div>;

type State = BaseRoomStoreState & AiSliceState;

export const {roomStore, useRoomStore} = createRoomStore<State>(
  (set, get, store) => ({
    ...createBaseRoomSlice()(set, get, store),
    ...createAiSlice({
      getInstructions: () => 'You are a helpful analytics assistant.',
      tools: {
        echo: tool({
          description: 'Echo text back',
          inputSchema: z.object({text: z.string()}),
          execute: async ({text}) => ({success: true, text: `Echo: ${text}`}),
        }),
      },
      toolRenderers: {
        echo: EchoResult,
      },
    })(set, get, store),
  }),
);

```

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

### Migrate Project Setup to RoomShell

Source: https://sqlrooms.org/upgrade-guide

Version 0.17.0 introduced a renaming of 'project' to 'room' and component changes. The `ProjectBuilderProvider` setup is replaced by the `RoomShell` component with its own sub-components.

```tsx
<ProjectBuilderProvider projectStore={projectStore}>
  <div className="flex h-full w-full">
    <div className="bg-muted/50 flex h-full flex-col px-1 py-2">
      <ProjectBuilderSidebarButtons />
    </div>
    <div className="flex h-full w-full flex-col">
      <ProjectBuilder />
    </div>
  </div>
</ProjectBuilderProvider>
```

```tsx
<RoomShell className="h-screen" roomStore={roomStore}>
  <RoomShell.Sidebar />
  <RoomShell.LayoutComposer />
  <RoomShell.LoadingProgress />
  <RoomShell.CommandPalette />
</RoomShell>
```

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

### Feature Flag Middleware Example

Source: https://sqlrooms.org/commands

An example of command middleware that checks if a command is enabled by feature flags before execution. If disabled, it returns an error; otherwise, it proceeds to the next middleware or the command execution.

```typescript
const featureFlagMiddleware = async (command, input, context, next) => {
  const enabled = context
    .getState()
    .features.enabledCommands.includes(command.id);
  if (!enabled) {
    return {
      success: false,
      commandId: command.id,
      code: 'command-disabled-by-feature-flag',
      error: `Command "${command.name}" is disabled by feature flags.`,
    };
  }
  return await next();
};
```

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

### Set up Room Store with SQL Editor Slice

Source: https://sqlrooms.org/api/sql-editor

Configure the room store by combining the room shell slice with the SQL editor slice. This setup includes defining data sources for the SQL editor.

```tsx
import {
  createRoomShellSlice,
  createRoomStore,
  RoomShellSliceState,
} from '@sqlrooms/room-shell';
import {createSqlEditorSlice, SqlEditorSliceState} from '@sqlrooms/sql-editor';

type RoomState = RoomShellSliceState & SqlEditorSliceState;

export const {roomStore, useRoomStore} = createRoomStore<RoomState>(
  (set, get, store) => ({
    ...createRoomShellSlice({
      config: {
        dataSources: [
          {
            type: 'url',
            tableName: 'earthquakes',
            url: 'https://huggingface.co/datasets/sqlrooms/earthquakes/resolve/main/earthquakes.parquet',
          },
        ],
      },
    })(set, get, store),
    ...createSqlEditorSlice()(set, get, store),
  }),
);

```

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

### getCommandInputComponent

Source: https://sqlrooms.org/api/room-store

Gets the input component for a command.

```APIDOC
## getCommandInputComponent

### Description
Gets the input component for a command.

### Function Signature
`getCommandInputComponent(command: Command): React.ComponentType | null`
```

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

### getCommandKeystrokes

Source: https://sqlrooms.org/api/room-store

Gets the keystrokes associated with a command.

```APIDOC
## getCommandKeystrokes

### Description
Gets the keystrokes associated with a command.

### Function Signature
`getCommandKeystrokes(command: Command): string[]`
```

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

### getCommandShortcut

Source: https://sqlrooms.org/api/room-store

Gets the shortcut key for a command.

```APIDOC
## getCommandShortcut

### Description
Gets the shortcut key for a command.

### Function Signature
`getCommandShortcut(command: Command): string | null`
```

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

### Get an Artifact

Source: https://sqlrooms.org/api/artifacts

Retrieves an artifact by its ID.

```javascript
artifacts.getArtifact(id)
```

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

### getChildrenIds

Source: https://sqlrooms.org/api/layout-config

Gets the IDs of all direct children of a layout node.

```APIDOC
## getChildrenIds

### Description
Retrieves an array of IDs for all immediate child nodes of a given layout node.

### Method
N/A (Function)

### Endpoint
N/A (Function)

### Parameters
None explicitly documented for this function signature.

### Request Example
N/A (Function)

### Response
N/A (Function - returns an array of child node IDs)
```

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

### Basic Layout Configuration

Source: https://sqlrooms.org/api/layout-config

Demonstrates creating a simple layout with just the main view and a two-pane split layout. The two-pane layout is validated using Zod.

```typescript
import {
  LayoutConfig,
  LayoutNode,
  createDefaultLayout,
} from '@sqlrooms/layout-config';

// Simplest config — just the main view
const simpleLayout = createDefaultLayout(); // returns 'main'

// Two-pane split layout
const twoPaneLayout: LayoutConfig = {
  type: 'split',
  direction: 'row',
  children: [
    {type: 'panel', id: 'data', defaultSize: '30%'},
    {type: 'panel', id: 'main', defaultSize: '70%'},
  ],
};

// Validated via Zod
const validated: LayoutConfig = LayoutConfig.parse(twoPaneLayout);
```

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

### Handle Nonexistent Database Error

Source: https://sqlrooms.org/api/ai-rag

Example of catching an error when querying a database that does not exist.

```typescript
try {
  const results = await store.getState().rag.queryByText('search query', {
    database: 'nonexistent',
  });
} catch (error) {
  // Error: Database "nonexistent" not found. Available: docs, tutorials
}
```

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

### Create Room Store with Initial Configuration

Source: https://sqlrooms.org/key-concepts

Initializes the roomStore using createRoomStore, providing initial configuration for data sources and layout. This is typically used at the application's entry point.

```tsx
const {roomStore, useRoomStore} = createRoomStore<
  RoomState
>(
  (set, get, store) => ({
    ...createRoomShellSlice({
      config: {
        dataSources: [
          {
            type: 'url',
            url: 'https://.../earthquakes.parquet',
            tableName: 'earthquakes',
          },
        ],
      },
      layout: {
        config: {
          // Layout configuration
        },
        panels: {
          // Panel definitions
        },
      },
    })(set, get, store),
  }),
);

```

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

### Basic Login Form with UI Components

Source: https://sqlrooms.org/api/ui

Demonstrates using Button, Card, and Input components from @sqlrooms/ui to create a simple login form.

```tsx
import {Button, Card, Input} from '@sqlrooms/ui';

function LoginForm() {
  return (
    <Card className="mx-auto max-w-md p-6">
      <h2 className="mb-4 text-2xl font-bold">Login</h2>
      <form>
        <div className="space-y-4">
          <div>
            <Input type="email" placeholder="Email" required />
          </div>
          <div>
            <Input type="password" placeholder="Password" required />
          </div>
          <Button type="submit" className="w-full">
            Sign In
          </Button>
        </div>
      </form>
    </Card>
  );
}
```

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

### Create Room Store with Initial Configuration

Source: https://sqlrooms.org/getting-started

Initialize the room store by combining the room shell slice with your custom state and logic. Configure initial data sources and layout.

```typescript
import {DatabaseIcon} from 'lucide-react';
import {MainView} from './components/MainView';
import {DataSourcesPanel} from './components/DataSourcesPanel';

/**
 * Create the room store. You can combine your custom state and logic
 * with the slices from the SQLRooms modules.
 */
export const {roomStore, useRoomStore} = createRoomStore<RoomState>(
  (set, get, store) => ({
    ...createRoomShellSlice({
      config: {
        title: 'My SQLRooms App',
        dataSources: [
          {
            tableName: 'earthquakes',
            type: 'url',
            url: 'https://huggingface.co/datasets/sqlrooms/earthquakes/resolve/main/earthquakes.parquet',
          },
        ],
      },
      layout: {
        config: {
          type: 'split',
          direction: 'row',
          children: [
            {type: 'panel', id: 'data-sources', defaultSize: '30%'},
            'main',
          ],
        },
        panels: {
          'data-sources': {
            title: 'Data Sources',
            icon: DatabaseIcon,
            component: DataSourcesPanel,
          },
          main: {
            title: 'Main view',
            icon: () => null,
            component: MainView,
          },
        },
      },
    })(set, get, store),

    // Add additional slices if needed
    // ...createSqlEditorSlice()(set, get, store),
  }),
);

```

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

### Old SQLROOMS API Query

Source: https://sqlrooms.org/query-cancellation

Example of executing a query using the previous SQLROOMS API.

```typescript
const {data, qid} = await connector.query('SELECT * FROM table');
console.log('Query ID:', qid);
console.log('Results:', data.numRows);
```

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

### Create, Add, and Drop Tables with SQL generasi

Source: https://sqlrooms.org/api/duckdb

Demonstrates direct database operations using the useRoomStore hook. Includes creating tables from SQL queries, adding tables from JavaScript objects, and dropping tables.

```tsx
import {useRoomStore} from './store';
import {Button} from '@sqlrooms/ui';

function DatabaseManager() {
  const createTableFromQuery = useRoomStore(
    (state) => state.db.createTableFromQuery,
  );
  const addTable = useRoomStore((state) => state.db.addTable);
  const dropTable = useRoomStore((state) => state.db.dropTable);
  const tables = useRoomStore((state) => state.db.tables);
  const refreshTableSchemas = useRoomStore(
    (state) => state.db.refreshTableSchemas,
  );

  // Create a table from a query
  const handleCreateTable = async () => {
    const result = await createTableFromQuery(
      'filtered_users',
      'SELECT * FROM users WHERE active = true',
    );
    console.log(`Created table with ${result.rowCount} rows`);
  };

  // Add a table from JavaScript objects
  const handleAddTable = async () => {
    const users = [
      {id: 1, name: 'Alice', email: 'alice@example.com'},
      {id: 2, name: 'Bob', email: 'bob@example.com'},
    ];
    await addTable('new_users', users);
  };

  // Drop a table
  const handleDropTable = async () => {
    await dropTable('old_table');
  };

  return (
    <div>
      <Button onClick={handleCreateTable}>Create Filtered Users Table</Button>
      <Button onClick={handleAddTable}>Add New Users Table</Button>
      <Button onClick={handleDropTable}>Drop Old Table</Button>
      <Button onClick={refreshTableSchemas}>Refresh Schemas</Button>

      <h3>Available Tables:</h3>
      <ul>
        {tables.map((table) => (
          <li key={table.table.toString()}>
            {table.table.toString()} ({table.columns.length} columns)
          </li>
        ))}
      </ul>
    </div>
  );
}

```

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

### SQLRooms Theme Provider Setup

Source: https://sqlrooms.org/theming

Set up the ThemeProvider at the root of your application to manage theme state and persistence. Use 'defaultTheme' to set the initial theme and 'storageKey' to define the localStorage key for saving user preferences.

```tsx
<ThemeProvider defaultTheme="dark" storageKey="sqlrooms-ui-theme">
  <App />
</ThemeProvider>
```

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

### Start and Cancel a Basic Query

Source: https://sqlrooms.org/query-cancellation

Initiates a query and provides a handle to cancel it. Useful for user-initiated cancellations.

```typescript
import {createWasmDuckDbConnector} from './connectors/createDuckDbConnector';

const connector = createWasmDuckDbConnector();
await connector.initialize();

// Start a query and get immediate access to cancellation
const queryHandle = connector.query('SELECT * FROM large_table');
console.log('Query started');

// Cancel the query if needed (e.g., user clicks cancel button)
setTimeout(() => {
  queryHandle.cancel();
}, 5000);

try {
  const result = await queryHandle;
  console.log('Query completed:', result.numRows);
} catch (error) {
  console.log('Query was cancelled or failed:', error.message);
}
```

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

### getAiRunContextPrimaryItem

Source: https://sqlrooms.org/api/ai-config

Retrieves the primary AI run context item. This is useful for getting the most relevant or current context.

```APIDOC
## getAiRunContextPrimaryItem

### Description
Retrieves the primary AI run context item.

### Function Signature
getAiRunContextPrimaryItem(): AiRunContextItem | undefined
```