> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scoutos.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Creating Scout Databases, Tables, and Column Schemas
> Set up Scout Databases and Tables for your agents. Define column schemas, configure metadata fields, and prepare your knowledge base for semantic search.
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
Navigate to Databases in the left-hand sidebar of the Scout dashboard.
Click **+ New** at the top of the page. A creation dialog appears.
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.
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
```bash cURL theme={null}
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"
}'
```
```python Python theme={null}
from scoutos import Scout
client = Scout(api_key="YOUR_API_KEY")
database = client.databases.create(
name="Knowledge Base",
description="Product documentation and support articles"
)
print(database)
# {'id': 'col_abc123', 'name': 'Knowledge Base', ...}
```
```typescript TypeScript theme={null}
import { ScoutClient } from "scoutos";
const client = new ScoutClient({ apiKey: "YOUR_API_KEY" });
const database = await client.databases.create({
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
Click the table name in the Database view to open it.
Click the **+** button in the table header row.
Enter a column name (use `snake_case`, for example `updated_at` or `category`) and select a column type from the list below.
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:
Best for small datasets or one-off additions. Click **+ Add Document** in the table view and fill in the fields directly.
Best for live data that changes regularly. Connect Notion, Google Sheets, or a website and let Scout sync automatically on a schedule.
Best for bulk imports and programmatic ingestion from your own applications.
Best for saving data produced by an agent or workflow step directly into a table.
### Manual Entry
1. Open your table in Scout Studio.
2. Click **+ Add Document** or click in any empty row.
3. Fill in the fields.
4. Click **Save**.
### Via the API or SDK
```bash cURL theme={null}
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
}
]
}'
```
```python Python theme={null}
from scoutos import Scout
client = Scout(api_key="YOUR_API_KEY")
# Add a single document
client.documents.create(
collection_id="col_abc123",
table_id="tab_xyz789",
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
}]
)
# Add multiple documents in a single request
client.documents.create(
collection_id="col_abc123",
table_id="tab_xyz789",
documents=[
{"id": "doc_001", "title": "Doc 1", "content": "...", "category": "tutorial"},
{"id": "doc_002", "title": "Doc 2", "content": "...", "category": "reference"},
{"id": "doc_003", "title": "Doc 3", "content": "...", "category": "tutorial"}
]
)
```
```typescript TypeScript theme={null}
import { ScoutClient } from "scoutos";
const client = new ScoutClient({ apiKey: "YOUR_API_KEY" });
// Add a single document
await client.documents.create({
collectionId: "col_abc123",
tableId: "tab_xyz789",
documents: [{
id: "doc_001",
title: "Getting Started Guide",
content: "This comprehensive guide walks you through...",
url: "https://docs.example.com/getting-started",
category: "tutorial",
updatedAt: 1704067200
}]
});
// Add multiple documents
await client.documents.create({
collectionId: "col_abc123",
tableId: "tab_xyz789",
documents: [
{ id: "doc_001", title: "Doc 1", content: "...", category: "tutorial" },
{ id: "doc_002", title: "Doc 2", content: "...", category: "reference" },
{ id: "doc_003", title: "Doc 3", content: "...", category: "tutorial" }
]
});
```
### Via Workflow Blocks
Use the **Save Document to Table** block inside any Scout workflow:
1. Add the block to your workflow canvas.
2. Select the target Database and Table from the dropdowns.
3. Map workflow output values to the appropriate table columns.
4. Run the workflow — documents are upserted automatically.
## Document Structure
Every document follows this general shape:
```json theme={null}
{
"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
}
```
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.
The primary text body. This field is automatically chunked and embedded for semantic search. Write comprehensive, descriptive content here for the best retrieval quality.
A short label for the document. Returned in search results and displayed in the Scout UI.
Any custom metadata field. Metadata columns are used for filtering, sorting, and display — they are not embedded.
## Managing Tables
### View a Table's Schema
```bash theme={null}
curl https://api.scoutos.com/v2/collections/{collection_id}/tables/{table_id}/schema \
-H "Authorization: Bearer YOUR_API_KEY"
```
### Rename a Table
```bash theme={null}
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.
```bash theme={null}
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:
```markdown theme={null}
When creating or updating table records:
1. Validate the target database and table before writing.
2. Confirm required fields are present: id, content, and key metadata.
3. Use consistent values for taxonomy fields like category and status.
4. If data is incomplete, ask for missing fields before saving.
5. 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
Automate data ingestion from Notion, Google Sheets, and the web.
Search databases with semantic, keyword, and hybrid modes.
Understand the full Databases data model and when to use it.