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

How to use it?

Basic Command Structure

/selected-datastore [action] [key | key+sortField | itemId] [content]

Parameters

Required:

action - Operation to perform (create, read, update, delete, search, list)
collection - Collection ID for data isolation (automatically set when you select a collection from the slash command menu)

Required (one of):

key - Primary identifier for your item
itemId - Unique document ID
key + sortField - Primary and secondary identifiers for specific item

Optional:

sortField - Secondary identifier that makes the item unique when combined with key
content - The main content of your item
metadata - Custom attributes as a JSON object
triggerUrls - Array of trigger objects that fire when the item changes (see Triggers section)

For tables:

metadata: {
  "displayType": "csv",
  "csvData": "Month,Revenue,Units\nJan,50000,500\nFeb,55000,550"
}

Response Format

Single item:

{
  "id": "unique item ID",
  "key": "your key",
  "sortField": "your sort field",
  "content": "stored data",
  "createdAt": "2025-01-09T00:40:35.303Z",
  "updatedAt": "2025-01-09T00:40:35.303Z",
  "metadata": {}
}

List of items (light format):

[
  {
    "id": "myKey1",
    "createdAt": "2025-01-09T00:40:35.303Z",
    "sortField": "mySortField",
    "key": "myKey1",
    "updatedAt": "2025-01-09T00:40:35.303Z"
  }
]

Tools

Create/Update Item

Create a new item or update an existing one. If key and sortField already exist, this will update the existing item. Parameters:

action (required) - Set to “create” or “update”
key (required) - Primary identifier
content (optional) - Item content
sortField (optional) - Secondary identifier
metadata (optional) - Custom attributes
triggerUrls (optional) - Array of trigger objects (see Triggers section)
triggerChanges (optional) - Set to false to prevent firing triggers

Example:

/selected-datastore create a new item with:
key: user123
content: {"name": "John Doe", "email": "john@example.com"}

Read Items

Retrieve items from the datastore Parameters:

action (required) - Set to “read” or “get”

Required (one of):

key - Primary identifier (returns all items with that key)
key + sortField - Primary and secondary identifiers for specific item
itemId - Unique document ID

Examples: By item ID:

/selected-datastore get item with itemId: abc123def456

By key and sort field:

/selected-datastore get item with key: projects and sortField: mobile-app-redesign

By key only (returns all items with that key):

/selected-datastore get items with key: projects

List All Items

Retrieve all items with optional filtering and pagination Parameters:

action (required) - Set to “list”
limit (optional) - Maximum number of results (default: 50, max: 1000)
orderedBy (optional) - Sort field and direction (e.g., “createdAt:desc”)
format (optional) - Set to “light” for minimal information

Example:

/selected-datastore list items with:
limit: 50
orderedBy: createdAt:desc
format: light

Update Item by ID

Update an existing item using its unique ID Parameters:

action (required) - Set to “update”
itemId (required) - Unique document ID
content (optional) - Updated content
metadata (optional) - Updated metadata
triggerChanges (optional) - Set to false to prevent firing triggers

Examples: Update with triggers:

/selected-datastore update item with:
itemId: abc123def456
content: Updated project documentation

Update without firing triggers:

/selected-datastore update item with:
itemId: abc123def456
content: Updated content
triggerChanges: false

Delete Item

Remove an item from the datastore Parameters:

action (required) - Set to “delete”

Required (one of):

itemId - Unique document ID (recommended)
key - Primary identifier (deletes all items with that key)
key + sortField - Primary and secondary identifiers for specific item

Examples: By item ID (recommended):

/selected-datastore delete item with itemId: abc123def456

By key and sort field:

/selected-datastore delete item with key: projects and sortField: mobile-app-redesign

By key only (deletes all items with that key):

/selected-datastore delete items with key: projects

Search Items

Search for items in the datastore with advanced filtering Parameters:

action (required) - Set to “search”
q (required) - Search query string
field (optional) - Field to search: “all” (default), “content”, “sortField”, “key”
type (optional) - Search type: “fuzzy” (default), “exact”, “prefix”
threshold (optional) - Fuzzy sensitivity 0.0 (strict) to 1.0 (lenient), default: 0.3
limit (optional) - Max results (default: 50, max: 1000)
compiled (optional) - Output format: false (default - JSON with snippets), true (plain text)
content.* (optional) - Filter by content fields
metadata.* (optional) - Filter by metadata fields

Examples: Basic search:

/selected-datastore search
q: customer feedback
field: content
type: fuzzy

Advanced search with filters:

/selected-datastore search
q: genoa
field: content
type: exact
metadata.category: work
compiled: false

Search Response (compiled=false):

{
  "results": [
    {
      "docId": "8CTVmqIIJDmDGN5HpYm5",
      "fieldMatched": "content",
      "matchedSnippet": "...Well, Prince, so **Genoa** and Lucca are now just family estates...",
      "score": 0.84,
      "relevance": "high"
    }
  ]
}

Search Response (compiled=true):

ID: 8CTVmqIIJDmDGN5HpYm5
Content: Well, Prince, so Genoa and Lucca are now just family estates of the Buonapartes.

ID: EPScUGDABP2xQWgphvcc
Content: Well, Prince, so Genoa and Lucca are now just family estates of the Buonapartes.

What can you do with it?

Store, retrieve, update, and search data in a NoSQL datastore. Perfect for managing structured data with key-value pairs, metadata, and optional sorting capabilities. Ideal for user preferences, application state, dynamic content, and any data that needs persistent storage with search functionality.

Key and Sort Field Fundamentals

Important Rules

The combination of key + sortField must be unique within a collection
If you don’t specify a sortField, one will be automatically generated for you
You can have multiple items with the same key as long as they have different sortField values
Think of key as a folder name and sortField as a unique identifier within that folder
Working with itemId is the most direct and efficient way to interact with datastore items

Key and Sort Field Patterns

Single Key Only (Auto-generated Sort Field)
```
key: meeting-notes
```
- Sort field will be auto-generated
- Good for: Quick storage when uniqueness isn’t a concern
Key + Date Sort Field
```
key: meeting-notes
sortField: 2024-03-15
```
- Creates unique daily entries
- Good for: Time-series data, daily logs
Key + Email Sort Field
```
key: employee-reviews
sortField: jane.smith@company.com
```
- One record per employee
- Good for: Per-user data
Key + Category Sort Field
```
key: inventory
sortField: electronics-001
```
- Unique identifier within category
- Good for: Categorized items requiring unique IDs

Examples

Project Documentation

/selected-datastore create a new item with:
key: projects
sortField: mobile-app-redesign
content: Mobile App Redesign Documentation
metadata: {
    "status": "in-progress",
    "team": "design"
}

Sales Reports by Region

/selected-datastore create a new item with:
key: sales-data
sortField: europe-2024-q1
content: European Region Q1 Sales
metadata: {
    "displayType": "csv",
    "csvData": "Country,Revenue,Units\nFrance,75000,750\nGermany,82000,820"
}

Employee Training Records

/selected-datastore create a new item with:
key: training-completion
sortField: alice.johnson@company.com
content: Security Training 2024
metadata: {
    "completionDate": "2024-03-15",
    "score": "95%"
}

Product Inventory by Category

/selected-datastore create a new item with:
key: inventory
sortField: smartphones
content: Smartphone Inventory
metadata: {
    "displayType": "csv",
    "csvData": "Model,Stock,Price\niPhone 15,50,999\nPixel 8,30,899"
}

Triggers

Datastore supports event-driven triggers that automatically start workflows when data changes. Triggers can be set at two levels: collection-wide (affects all items) or item-specific (affects individual items).

Trigger Events

onCreate: Fires when new items are created (collection-level only)
onEdit: Fires when existing items are modified (collection or item level)
onDelete: Fires when items are deleted (collection or item level)

Trigger Levels

Collection-Level Triggers: Set on the entire data collection to monitor all items

Automatically fire for every item in the collection
Perfect for system-wide monitoring and processing
Set via data collection management interface

Item-Level Triggers: Set on individual items to monitor specific data

Only fire for that particular item
Ideal for monitoring critical or sensitive data points
Set via the triggerUrls parameter when creating/updating items

Trigger Structure

Triggers use an array format with multiple trigger objects:

triggerUrls: [
  {
    "event": "onEdit",
    "url": "https://triggers.app.pinkfish.ai/ext/triggers/d2nia2isg8tc7112frtg",
    "apiKey": "your-api-key"
  },
  {
    "event": "onDelete",
    "url": "https://triggers.app.pinkfish.ai/ext/triggers/a3bcd4efg9ud8223hsui",
    "apiKey": "your-api-key-2"
  }
]

Trigger Payload

When triggers fire, they receive detailed information about the event: For onCreate and onDelete events:

{
  "event": "onCreate",
  "itemId": "abc123def456",
  "providerId": "user-id",
  "collectionId": "collection-id",
  "collectionType": "datastore",
  "key": "user-settings",
  "sortField": "theme-preferences",
  "content": { "theme": "dark", "language": "en" },
  "metadata": { "version": "1.0" },
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:30:00.000Z",
  "triggerLevel": "item"
}

For onEdit events (includes additional changed field):

{
  "event": "onEdit",
  "itemId": "abc123def456",
  "providerId": "user-id",
  "collectionId": "collection-id",
  "collectionType": "datastore",
  "key": "user-settings",
  "sortField": "theme-preferences",
  "content": { "theme": "light", "language": "en" },
  "metadata": { "version": "1.1" },
  "changed": {
    "content": { "theme": "dark" },
    "metadata": { "version": "1.0" }
  },
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T11:45:00.000Z",
  "triggerLevel": "item"
}

Examples

Creating Item with Multiple Triggers

/selected-datastore create a new item with:
key: order-processing
sortField: order-12345
content: {"status": "pending", "amount": 299.99}
metadata: {"priority": "high", "customer": "customer-456"}
triggerUrls: [
  {
    "event": "onEdit",
    "url": "https://triggers.app.pinkfish.ai/ext/triggers/order-status-monitor",
    "apiKey": "your-api-key"
  },
  {
    "event": "onDelete",
    "url": "https://triggers.app.pinkfish.ai/ext/triggers/order-cancelled-handler",
    "apiKey": "your-api-key-2"
  }
]

Updating Item Status (Will Fire onEdit Triggers)

/selected-datastore update item with:
key: order-processing
sortField: order-12345
content: {"status": "shipped", "amount": 299.99, "tracking": "1Z999AA1234567890"}
metadata: {"priority": "high", "customer": "customer-456", "shipped_date": "2024-01-15"}

Updating Without Triggering

/selected-datastore update item with:
itemId: abc123def456
content: {"status": "processing", "internal_notes": "Updated by system"}
triggerChanges: false

Testing Triggers

Use the test-trigger endpoint to verify your trigger setup:

/selected-datastore test trigger with:
event: onEdit
url: https://triggers.app.pinkfish.ai/ext/triggers/d2nia2isg8tc7112frtg
apiKey: your-api-key
itemId: abc123def456
testData: {"test": true, "timestamp": "2024-01-15T12:00:00.000Z"}

Rate Limiting and Logs

Rate Limiting: onEdit triggers are limited to 2 executions per minute per item to prevent infinite loops
Trigger Logs: All trigger executions are logged with status, execution time, and error details
Error Handling: Failed triggers are logged but don’t prevent the original data operation from completing

Best Practices

Use Collection-Level Triggers for system-wide monitoring (e.g., audit logs, analytics)
Use Item-Level Triggers for specific business logic (e.g., order processing, user notifications)
Set triggerChanges: false when updating items programmatically to avoid recursive triggers
Test triggers thoroughly using the test-trigger endpoint before production use
Monitor trigger logs to ensure reliable execution and debug issues

Notes

Items are uniquely identified by key + sortField combination within a collection
Use itemId for direct access to specific items (most efficient method)
Search supports fuzzy, exact, and prefix matching with configurable thresholds
Triggers can notify external URLs on data changes
When updating, only sent values are replaced; others remain unchanged
GET operations by key/sortField return an array of items, but GET operations by specific itemId return a single object
When you select a collection from the slash command menu, the collection ID is automatically preset for you

Get Started

Organization

Agents

Workflows

Resources

Integrations

Orchestration

Credits & Pricing

Skills

How To Guides

Release Notes

Support

​How to use it?

​Basic Command Structure

​Parameters

​Response Format

​Tools

​Create/Update Item

​Read Items

​List All Items

​Update Item by ID

​Delete Item

​Search Items

​What can you do with it?

​Key and Sort Field Fundamentals

​Important Rules

​Key and Sort Field Patterns

​Examples

​Project Documentation

​Sales Reports by Region

​Employee Training Records

​Product Inventory by Category

​Triggers

​Trigger Events

​Trigger Levels

​Trigger Structure

​Trigger Payload

​Examples

​Creating Item with Multiple Triggers

​Updating Item Status (Will Fire onEdit Triggers)

​Updating Without Triggering

​Testing Triggers

​Rate Limiting and Logs

​Best Practices

​Notes

How to use it?

Basic Command Structure

Parameters

Response Format

Tools

Create/Update Item

Read Items

List All Items

Update Item by ID

Delete Item

Search Items

What can you do with it?

Key and Sort Field Fundamentals

Important Rules

Key and Sort Field Patterns

Examples

Project Documentation

Sales Reports by Region

Employee Training Records

Product Inventory by Category

Triggers

Trigger Events

Trigger Levels

Trigger Structure

Trigger Payload

Examples

Creating Item with Multiple Triggers

Updating Item Status (Will Fire onEdit Triggers)

Updating Without Triggering

Testing Triggers

Rate Limiting and Logs

Best Practices

Notes