Resource management: models, prompts, and API keys

Flock treats models, prompts, and API credentials as first-class SQL resources. You create and manage them with dedicated SQL commands — no config files, no environment variables to juggle across sessions. Each resource type has its own storage table that is initialized per database when Flock loads, and every resource can be scoped as either local (the current database) or global (shared across all databases in the session).

Models
Prompts
API keys / secrets

Model configuration

A model record maps a short model_name alias to the underlying provider model, its serialization format, batching behavior, and any provider-specific parameters. The fields stored for each model are:

model_name

string

required

Unique alias you use to reference this model in LLM function calls (e.g., 'gpt-4o').

model_type

string

required

The underlying model identifier as the provider expects it (e.g., 'gpt-4o', 'llama3.1').

provider

string

required

The provider that serves the model. One of openai, azure, ollama, or anthropic.

tuple_format

string

default:"XML"

How input rows are serialized into the prompt. One of JSON, XML, or Markdown. Defaults to XML when not specified.

batch_size

integer

default:"2048"

Maximum number of rows passed to the model in a single API call. Defaults to 2048 when not specified.

model_parameters

object

Provider-specific parameters passed directly to the API (e.g., temperature, top_p, n, frequency_penalty). Expressed as a JSON object.

Reading models

-- List all available models (system-defined and user-defined)
GET MODELS;

-- Inspect a specific model
GET MODEL 'model_name';

Creating models

Omitting the config object uses the defaults for tuple_format (XML) and batch_size (2048):

-- Minimal: no config object
CREATE MODEL('my-gpt4o', 'gpt-4o', 'openai');

-- With JSON tuple format and temperature
CREATE MODEL(
    'my-gpt4o',
    'gpt-4o',
    'openai',
    {
        "tuple_format": "JSON",
        "batch_size": 8,
        "model_parameters": {
            "temperature": 0.2,
            "top_p": 0.95
        }
    }
);

-- With XML tuple format
CREATE MODEL(
    'my-llama',
    'llama3.1',
    'ollama',
    {
        "tuple_format": "XML",
        "batch_size": 8,
        "model_parameters": {
            "n": 3,
            "frequency_penalty": 0.1
        }
    }
);

-- With Markdown tuple format
CREATE MODEL(
    'my-claude',
    'claude-opus-4-5',
    'anthropic',
    {
        "tuple_format": "Markdown",
        "batch_size": 8
    }
);

Global and local models

By default, a model is local to the current database. Use CREATE GLOBAL MODEL to make it available across all databases:

-- Global model — available in all databases
CREATE GLOBAL MODEL(
    'shared-gpt4o',
    'gpt-4o',
    'openai',
    {
        "tuple_format": "JSON",
        "batch_size": 8,
        "model_parameters": {
            "temperature": 0.2,
            "top_p": 0.95
        }
    }
);

-- Local model — explicit keyword, same as the default
CREATE LOCAL MODEL('local-llama', 'llama3.1', 'ollama');

-- Promote or demote an existing model
UPDATE MODEL 'shared-gpt4o' TO LOCAL;
UPDATE MODEL 'local-llama' TO GLOBAL;

Updating and deleting models

-- Update model (same config rules as CREATE)
UPDATE MODEL(
    'my-gpt4o',
    'gpt-4o',
    'openai',
    {
        "tuple_format": "JSON",
        "batch_size": 16,
        "model_parameters": {
            "temperature": 0.5
        }
    }
);

-- Delete a model
DELETE MODEL 'my-gpt4o';

Using a model in a query

Reference the model by its model_name alias in any Flock LLM function:

SELECT llm_complete(
    {'model_name': 'my-gpt4o'},
    {'prompt_name': 'product-description'},
    {'input_text': product_description}
) AS generated_description
FROM products;

Prompt table structure

Each prompt record stores a name, the prompt text, a version number, and a last-updated timestamp. Flock always resolves to the latest version unless you specify one explicitly.

Field	Description
`prompt_name`	Unique identifier for the prompt
`prompt`	Instruction content passed to the model
`version`	Auto-incremented integer; increases on each update
`updated_at`	Timestamp of the last modification

Reading prompts

-- List all prompts
GET PROMPTS;

-- Inspect a specific prompt (returns all versions)
GET PROMPT 'prompt_name';

Creating prompts

CREATE PROMPT('product-description', 'Write a one-sentence product description for the following item.');

Global and local prompts

Like models, prompts are local by default. Use CREATE GLOBAL PROMPT to share across databases:

-- Global prompt — available in all databases
CREATE GLOBAL PROMPT('shared-summarizer', 'Summarize the following text in three bullet points.');

-- Local prompt — explicit keyword, same as the default
CREATE LOCAL PROMPT('local-classifier', 'Classify the following review as positive, negative, or neutral.');
CREATE PROMPT('local-classifier', 'Classify the following review as positive, negative, or neutral.');

-- Promote or demote an existing prompt
UPDATE PROMPT 'local-classifier' TO GLOBAL;
UPDATE PROMPT 'shared-summarizer' TO LOCAL;

Updating and deleting prompts

Each UPDATE PROMPT call creates a new version while keeping the previous versions accessible by their version number:

-- Update prompt text (increments version)
UPDATE PROMPT('product-description', 'Write a compelling two-sentence product description for the following item.');

-- Delete a prompt
DELETE PROMPT 'product-description';

Using named prompts in queries

Reference a prompt by name in any Flock LLM function. Flock resolves to the latest version unless you specify one:

-- Use the latest version of a prompt
SELECT llm_complete(
    {'model_name': 'gpt-4o'},
    {'prompt_name': 'product-description'},
    {'input_text': product_description}
) AS generated_description
FROM products;

-- Pin to a specific version
SELECT llm_complete(
    {'model_name': 'semantic_search_model'},
    {'prompt_name': 'customer-review-summary', 'version': 3},
    {'customer_review': review_text}
) AS review_summary
FROM reviews;

Pin to a specific version in production queries to avoid prompt changes silently affecting downstream results. Use the latest-version shorthand during experimentation.

How Flock stores credentials

Flock uses DuckDB’s Secrets Manager for all provider credentials. Secrets are typed by provider and can be temporary (in-memory, lost when the session ends) or persistent (written to disk and reloaded automatically).Supported secret types:

Secret type	Provider
`OPENAI`	OpenAI
`OLLAMA`	Ollama (self-hosted)
`AZURE_LLM`	Azure OpenAI
`ANTHROPIC`	Anthropic / Claude

When no secret name is specified, DuckDB assigns a default name in the format __default_<provider> (e.g., __default_openai). Flock resolves this default automatically when you reference a model backed by that provider.

Creating secrets

CREATE SECRET (
    TYPE OPENAI,
    API_KEY 'your-api-key'
);
-- Creates __default_openai

Persistent secrets

Persistent secrets survive DuckDB session restarts. Use CREATE PERSISTENT SECRET to write the credential to disk:

CREATE PERSISTENT SECRET (
    TYPE OPENAI,
    API_KEY 'your-api-key'
);

Using a named secret with a model

If you have multiple secrets for the same provider (e.g., different API keys for different projects), create the secret with a custom name and reference it via secret_name when calling an LLM function:

-- Create a named secret
CREATE SECRET my_project_key (
    TYPE OPENAI,
    API_KEY 'your-project-specific-api-key'
);

-- Reference it in a query
SELECT llm_complete(
    {
        'model_name': 'gpt-4o',
        'secret_name': 'my_project_key'
    },
    {'prompt': 'Summarize this text.'},
    {'text': body}
) AS summary
FROM articles;

Listing and deleting secrets

-- List all secrets
FROM duckdb_secrets();

-- Delete a temporary secret
DROP TEMPORARY SECRET __default_openai;

-- Delete a persistent secret
DROP PERSISTENT SECRET __default_openai;

Deleting a secret that a model depends on will cause queries using that model to fail at runtime. Make sure any model referencing a secret has an alternative credential available before dropping it.

Get Started

SQL Functions

Multimodal

Advanced Features

Development

Resource management: models, prompts, and API keys

Model configuration

Reading models

Creating models

Global and local models

Updating and deleting models

Using a model in a query

Prompt table structure

Reading prompts

Creating prompts

Global and local prompts

Updating and deleting prompts

Using named prompts in queries

How Flock stores credentials

Creating secrets

Persistent secrets

Using a named secret with a model

Listing and deleting secrets

Build docs developers (and LLMs) love

Get Started

SQL Functions

Multimodal

Advanced Features

Development

Documentation Index

​Model configuration

​Reading models

​Creating models

​Global and local models

​Updating and deleting models

​Using a model in a query

​Prompt table structure

​Reading prompts

​Creating prompts

​Global and local prompts

​Updating and deleting prompts

​Using named prompts in queries

​How Flock stores credentials

​Creating secrets

​Persistent secrets

​Using a named secret with a model

​Listing and deleting secrets

Build docs developers (and LLMs) love

Model configuration

Reading models

Creating models

Global and local models

Updating and deleting models

Using a model in a query

Prompt table structure

Reading prompts

Creating prompts

Global and local prompts

Updating and deleting prompts

Using named prompts in queries

How Flock stores credentials

Creating secrets

Persistent secrets

Using a named secret with a model

Listing and deleting secrets