Creating Scout Databases, Tables, and Column Schemas

Databases are the data layer for your Scout agents. Before an agent can search your knowledge base or retrieve structured records, you need a Database with at least one Table and a defined schema. This page walks you through creating a Database in Scout Studio, configuring its Tables with typed columns, and getting data into them — both manually and via the API.

Creating a Database

From Scout Studio

Open the Databases section

Navigate to Databases in the left-hand sidebar of the Scout dashboard.

Create a new Database

Click + New at the top of the page. A creation dialog appears.

Fill in the details

Provide the following:

Name (required) — A clear, descriptive name, for example Product Knowledge Base or Support FAQs.
Description (optional) — A short note about what this Database contains.
Icon (optional) — A visual identifier to help distinguish it in the sidebar.

Click Create

Scout provisions and indexes your Database. This typically takes about 30 seconds. The UI shows the current provisioning status — wait for it to finish before adding data.

Via the API

curl -X POST https://api.scoutos.com/v2/collections \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Knowledge Base",
    "description": "Product documentation and support articles"
  }'

Configuring Tables

Every new Database comes with one Untitled table. You can rename it and add columns to match your data model. Tables act as distinct namespaces within a Database — for example, a Help Center Database might have an FAQs table and a Troubleshooting Guides table.

Adding Columns

Open your table

Click the table name in the Database view to open it.

Add a column

Click the + button in the table header row.

Name and type the column

Enter a column name (use snake_case, for example updated_at or category) and select a column type from the list below.

Save

Click Save or press Enter. The column appears immediately in the table schema.

Column Types

Type	Description	Best For
Single Line Text	Short plain-text entries	Titles, category tags, IDs
Multi Line Text	Long-form text content	Descriptions, articles, notes
Number	Integer or decimal values	Prices, counts, Unix timestamps
Checkbox	Boolean true/false flag	Status flags, completion state
URL	A valid web address	Source links, reference URLs

Example Schema: Documentation Table

For a product documentation knowledge base, use this column layout:

Column	Type	Purpose
`title`	Single Line Text	Article title displayed in search results
`content`	Multi Line Text	Full article text — indexed for semantic search
`url`	URL	Original source URL for attribution
`category`	Single Line Text	Topic classification for filtering
`updated_at`	Number	Unix timestamp of the last update

The `content` Column

The content column receives special treatment during indexing:

Automatic chunking — Long content is split into chunks of roughly 2,500 characters so that each chunk fits within the embedding model’s context window.
Vector embeddings — Each chunk gets its own embedding, enabling fine-grained semantic matches within long documents.
Linked results — Query results link back to the parent document so you always know which record matched.

Store all primary searchable text in a column named content for the best semantic search results. Scout uses this column for automatic embedding when vector indexing is enabled.

Naming and Organizing Databases

Keep your Databases easy to navigate with a few consistent conventions:

Use descriptive, noun-based Database names (Customer Support, Product Catalog, Engineering Docs).
Use snake_case for column names (created_at, user_id, source_url).
Group related tables inside a single Database rather than creating many small Databases— it keeps context together and makes agent queries simpler.
Add a description to every Database so teammates (and agents) understand its purpose at a glance.

Adding Data

Choose the method that fits your workflow:

Manual Entry

Best for small datasets or one-off additions. Click + Add Document in the table view and fill in the fields directly.

Source Syncs

Best for live data that changes regularly. Connect Notion, Google Sheets, or a website and let Scout sync automatically on a schedule.

API / SDK

Best for bulk imports and programmatic ingestion from your own applications.

Workflow Blocks

Best for saving data produced by an agent or workflow step directly into a table.

Manual Entry

Open your table in Scout Studio.
Click + Add Document or click in any empty row.
Fill in the fields.
Click Save.

Via the API or SDK

curl -X POST https://api.scoutos.com/v2/collections/{collection_id}/tables/{table_id}/documents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "documents": [
      {
        "id": "doc_001",
        "title": "Getting Started Guide",
        "content": "This comprehensive guide walks you through...",
        "url": "https://docs.example.com/getting-started",
        "category": "tutorial",
        "updated_at": 1704067200
      }
    ]
  }'

Via Workflow Blocks

Use the Save Document to Table block inside any Scout workflow:

Add the block to your workflow canvas.
Select the target Database and Table from the dropdowns.
Map workflow output values to the appropriate table columns.
Run the workflow — documents are upserted automatically.

Document Structure

Every document follows this general shape:

{
  "id": "unique_document_id",
  "content": "Main searchable text that gets embedded...",
  "title": "Document Title",
  "category": "tutorial",
  "url": "https://docs.example.com/my-article",
  "updated_at": 1704067200
}

string

required

A unique identifier for the document. Used for upserts — if a document with this ID already exists, it is updated in place rather than duplicated.

content

string

The primary text body. This field is automatically chunked and embedded for semantic search. Write comprehensive, descriptive content here for the best retrieval quality.

title

string

A short label for the document. Returned in search results and displayed in the Scout UI.

Managing Tables

View a Table’s Schema

curl https://api.scoutos.com/v2/collections/{collection_id}/tables/{table_id}/schema \
  -H "Authorization: Bearer YOUR_API_KEY"

Rename a Table

curl -X PATCH https://api.scoutos.com/v2/collections/{collection_id}/tables/{table_id} \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Updated Table Name"}'

Delete a Table

Deleting a table permanently removes all documents and vector embeddings stored in it. This action cannot be undone.

curl -X DELETE https://api.scoutos.com/v2/collections/{collection_id}/tables/{table_id} \
  -H "Authorization: Bearer YOUR_API_KEY"

Using Databases with Agents

Once your Database has data, agents can read from and write to it.

1. Enable Databases Tools

In your agent’s Tools tab, enable the Databases tools to grant the agent permission to create and query documents.

2. Add an Instruction Snippet

Add the following to your agent’s system prompt:

When creating or updating table records:

Validate the target database and table before writing.
Confirm required fields are present: id, content, and key metadata.
Use consistent values for taxonomy fields like category and status.
If data is incomplete, ask for missing fields before saving.
After writing, return the record IDs that were created or updated.

3. Prompt Examples

“Create a release_notes record for version 2.8.0 with category platform.”
“Upsert these three customer call summaries into customer_feedback.”
“Check whether this document already exists by URL before creating a new row.”

Best Practices

Schema stability — Avoid renaming columns after syncing data. Source mappings and workflow blocks reference columns by name; renames break those connections.
Use id for upserts — Always supply a stable, unique id for each document so re-running ingestion doesn’t create duplicates.
Content length — Write comprehensive, descriptive text in the content field. Short or generic content produces weaker embeddings and lower-quality search results.
Timestamps — Include created_at and updated_at as Number columns (Unix timestamps) so you can filter by date range in queries.

Next Steps

Sources

Automate data ingestion from Notion, Google Sheets, and the web.

Querying Data

Search databases with semantic, keyword, and hybrid modes.

Databases Overview

Understand the full Databases data model and when to use it.

​Creating a Database

​From Scout Studio

​Via the API

​Configuring Tables

​Adding Columns

​Column Types

​Example Schema: Documentation Table

​The content Column

​Naming and Organizing Databases

​Adding Data

Manual Entry

Source Syncs

API / SDK

Workflow Blocks

​Manual Entry

​Via the API or SDK

​Via Workflow Blocks

​Document Structure

​Managing Tables

​View a Table’s Schema

​Rename a Table

​Delete a Table

​Using Databases with Agents

​1. Enable Databases Tools

​2. Add an Instruction Snippet

​3. Prompt Examples

​Best Practices

​Next Steps

Sources

Querying Data

Databases Overview

Creating a Database

From Scout Studio

Via the API

Configuring Tables

Adding Columns

Column Types

Example Schema: Documentation Table

The `content` Column

Naming and Organizing Databases

Adding Data

Manual Entry

Via the API or SDK

Via Workflow Blocks

Document Structure

Managing Tables

View a Table’s Schema

Rename a Table

Delete a Table

Using Databases with Agents

1. Enable Databases Tools

2. Add an Instruction Snippet

3. Prompt Examples

Best Practices

Next Steps