Structured Datastore - Pinkfish - AI Agents & Workflows for Getting Work Done

🚧 Coming SoonStructured Datastores are currently in development and will be available soon. Stay tuned for spreadsheet-like databases with natural language queries and AI-powered analysis.

Overview

Structured Datastores are spreadsheet-like databases with defined columns, schema validation, and powerful natural language querying capabilities. Think of them as SQL tables that you can query and modify using plain English.

Creating a Structured Datastore

API Endpoint

POST /datacollection/

Using a Template

Create from predefined templates (contacts, customer-orders, user-directory, etc.):

{
  "name": "My Customer Database",
  "description": "Customer contact information",
  "type": "datastore",
  "createdBy": "your-provider-id",
  "createdByName": "Your Name",
  "isStructured": true,
  "templateId": "contacts",
  "triggerUrls": []
}

Available Templates

Get list of templates:

GET /datacollection/templates

Common templates:

contacts - Contact management (Name, Email, Phone, Company)
customer-orders - Order tracking (Order ID, Customer, Date, Amount, Status)
user-directory - User management (Name, Email, Department, Role)
task-list - Task tracking (Title, Description, Status, Priority, Due Date)

From CSV Import

Automatically detect schema from your CSV file:

POST /datacollection/import-csv

Multipart form data:

file - CSV file to import
name - Collection name
schema - Generated schema from analyze-csv
createdByName - Your display name

Response:

{
  "collectionId": "abc123-collection-id",
  "message": "Collection created successfully",
  "imported": 150,
  "total": 150,
  "schema": {...}
}

With Custom Schema

Create with your own schema definition:

{
  "name": "Product Catalog",
  "type": "datastore",
  "createdBy": "your-provider-id",
  "createdByName": "Your Name",
  "isStructured": true,
  "schema": {
    "fields": [
      {
        "id": "f_1",
        "label": "Product Name",
        "type": "string",
        "required": true
      },
      {
        "id": "f_2",
        "label": "Price",
        "type": "number",
        "required": true
      },
      {
        "id": "f_3",
        "label": "Category",
        "type": "select",
        "required": false,
        "options": ["Electronics", "Clothing", "Books"]
      },
      {
        "id": "f_4",
        "label": "In Stock",
        "type": "boolean",
        "required": false
      }
    ],
    "nextFieldId": 5,
    "sortConfig": {
      "fields": ["Category", "Product Name"],
      "direction": "asc"
    }
  }
}

Schema field types:

string - Text data
number - Numeric values
boolean - True/false
date - ISO date strings
select - Dropdown options (requires options array)

Note: When creating with a schema, the isStructured flag is automatically set to true.

Key Features

Schema-based structure with defined columns (string, number, boolean, date, select)
Natural language queries - search and analyze data using plain English
Inline editing - click cells to edit data directly
AI-powered analysis - ask questions, get aggregations, generate charts
Column management - add, rename, delete columns via UI
Custom sorting - configure multi-field sort priority
CSV import/export - bulk import data with schema detection

Natural Language Queries

The preferred way to work with structured datastores. The AI automatically translates your natural language into proper queries.

Search for Data

Find specific rows using natural language:

/selected-datastore-structured search for high priority cases from last week

Returns filtered rows matching your criteria.

Ask Questions

Get AI-generated answers with optional charts and reports:

/selected-datastore-structured what is the average age of active users?

Analysis capabilities:

Aggregations (sum, average, count, min, max)
Trend analysis and comparisons
Generate charts (PNG, SVG)
Export results (CSV, JSON)
Create reports (PDF)

How it works:

AI first filters relevant rows
For ≤25 rows: quick analysis
For >25 rows: code execution with chart generation
Generated files available for 15 minutes

Traditional CRUD Operations

When you need precise control over data operations.

Create Item

/selected-datastore-structured create item with:
content: {
  "Name": "John Doe",
  "Email": "john@example.com", 
  "Age": 30,
  "Status": "Active"
}

Key points:

Use column names (Name, Email) not field IDs (f_1, f_2)
Backend automatically converts names to field IDs
sortField auto-generated from schema’s sortConfig

Batch Create

Create up to 500 items at once:

/selected-datastore-structured create batch with:
[
  {"content": {"Name": "Alice", "Email": "alice@test.com", "Department": "Engineering"}},
  {"content": {"Name": "Bob", "Email": "bob@test.com", "Department": "Marketing"}},
  {"content": {"Name": "Carol", "Email": "carol@test.com", "Department": "Sales"}}
]

Query with Filters

Use SQL-like operators for precise queries:

/selected-datastore-structured query where:
Status: Active
Age_gt: 25
Department_in: Engineering,Marketing
orderBy: createdAt:desc
limit: 50

Available operators:

Exact: Status=Active
Greater than: Age_gt=25, Age_gte=25
Less than: Age_lt=30, Age_lte=30
Not equal: Status_ne=Inactive
IN (OR): Status_in=Active,Pending (max 10 values)
Range: Score_gt=75&Score_lt=90

Update Item

Partial Update (PATCH) - Recommended for structured datastores Only updates specified fields, preserves others:

PATCH /memory/items/{itemId}?collectionId=xxx

{
  "content": {
    "Status": "Inactive",
    "ExitDate": "2024-01-15"
  }
}

All other fields (Name, Email, etc.) remain unchanged. sortField is automatically recalculated based on sortConfig. Full Replace (PUT) Replaces entire content object:

PUT /memory/items/{itemId}?collectionId=xxx

{
  "content": {
    "Name": "John Doe",
    "Email": "john@example.com",
    "Status": "Inactive",
    "ExitDate": "2024-01-15"
  }
}

All fields must be provided or they will be lost. Use PATCH for typical updates.

Delete Item

/selected-datastore-structured delete item with itemId: abc123

Event Triggers

Automatically start workflows when data changes in your structured datastore. Triggers can be set at collection-level (all items) or item-level (specific rows). Supported events:

onCreate - New rows added
onEdit - Existing rows modified
onDelete - Rows removed

For complete documentation on setting up triggers, payload formats, rate limiting, and best practices, see the Event Triggers guide. Quick example:

{
  "content": {"Name": "John", "Status": "Active"},
  "triggerUrls": [
    {
      "event": "onEdit",
      "url": "https://triggers.app.pinkfish.ai/ext/triggers/abc123",
      "apiKey": "your-api-key"
    }
  ]
}

Schema Management

View Schema

/selected-datastore-structured get schema

Shows columns, types, and sort configuration.

Add Column

Done via UI - click ”+ New Column” button, or update schema programmatically.

Configure Sort Priority

Set which columns control the default sort order:

/selected-datastore-structured migrate sort config:
sortConfig: {
  "fields": ["Status", "Priority", "Name"],
  "direction": "asc"
}

This regenerates sortField for ALL items (may take 30-60s for large collections).

CSV Import

Analyze CSV

Preview schema before importing:

/selected-datastore-structured analyze CSV file: [upload file]

Returns detected schema, sample data, and warnings.

Import CSV

Create new collection from CSV:

/selected-datastore-structured import CSV as new collection:
name: "Customer Database"
file: [upload file]
schema: [schema from analyze]

Or add to existing collection:

/selected-datastore-structured import CSV to this collection: [upload file]

Best Practices

Use Natural Language:

Start with natural language for finding and analyzing data
Fall back to CRUD for precise control or batch operations

Column Names vs Field IDs:

Always use column names (Name, Email, Status) in your requests
Backend handles field ID conversion automatically
Field IDs (f_1, f_2) are internal implementation details

Performance:

Max 10K items per query
Batch operations support up to 500 items
Natural answer processes up to 10K rows
Use limit parameter to reduce response size

Sorting:

Configure sortConfig for custom multi-field sorting
sortField auto-generated on create/update
Only sort by: createdAt, updatedAt, or sortField

Common Use Cases

Customer and contact databases with searchable fields
Product catalogs with filterable attributes
Employee directories with department filtering
Sales pipelines with status tracking
Inventory management with stock levels
Survey responses with demographic analysis
Task lists with priority and status filters

Notes

Structured collections require a schema before adding data
Use CSV import to quickly bootstrap from existing data
Schema can be modified after creation (add/remove columns)
Natural language queries handle complex filters automatically
Generated charts and reports expire after 15 minutes

Get Started

Organization

Agents

Workflows

Resources

Integrations

Orchestration

Credits & Pricing

Skills

How To Guides

Release Notes

Support

​Overview

​Creating a Structured Datastore

​API Endpoint

​Using a Template

​Available Templates

​From CSV Import

​With Custom Schema

​Key Features

​Natural Language Queries

​Search for Data

​Ask Questions

​Traditional CRUD Operations

​Create Item

​Batch Create

​Query with Filters

​Update Item

​Delete Item

​Event Triggers

​Schema Management

​View Schema

​Add Column

​Configure Sort Priority

​CSV Import

​Analyze CSV

​Import CSV

​Best Practices

​Common Use Cases

​Notes

Overview

Creating a Structured Datastore

API Endpoint

Using a Template

Available Templates

From CSV Import

With Custom Schema

Key Features

Natural Language Queries

Search for Data

Ask Questions

Traditional CRUD Operations

Create Item

Batch Create

Query with Filters

Update Item

Delete Item

Event Triggers

Schema Management

View Schema

Add Column

Configure Sort Priority

CSV Import

Analyze CSV

Import CSV

Best Practices

Common Use Cases

Notes