pinecone:n8n

What this skill does

# Pinecone n8n Workflow Skill

This skill helps you build n8n workflows with Pinecone nodes following best practices. It covers two Pinecone nodes:
- **Pinecone Assistant** (`@pinecone-database/n8n-nodes-pinecone-assistant`) — recommended for most use cases
- **Pinecone Vector Store** (`@n8n/n8n-nodes-langchain.vectorStorePinecone`) — for advanced control

**Core rule:** Always use the node's built-in resources and operations. Never suggest using the HTTP node to call the Pinecone REST API directly.

---

## Step 1: Understand the user's scenario

Ask the user what they're trying to do:
- Build a new workflow from scratch
- Configure or understand a specific Pinecone node
- Debug a workflow that isn't working
- Review an existing workflow for best practices

---

## Step 2: Node selection (for new workflows and configuration questions)

Always present the Pinecone Assistant node as the recommended choice first. Do NOT skip this step based on your own inference about which node fits better — even if the use case mentions specific triggers (Google Drive, webhooks, etc.) or file types (text, markdown, PDF), those details do not determine which node to use.

**Only skip this step if:**
- The user explicitly names a specific node (e.g. "I want to use the Vector Store node", "help me set up pineconeAssistant")
- The user is debugging or configuring an existing workflow that already has a specific Pinecone node in it

**If the user has not named a node, always ask or recommend the Assistant node first.** If the user said "use defaults" or you cannot ask, default to the Pinecone Assistant node and proceed with the Assistant path.

Ask the user which node they want to use, presenting these two options:

**Pinecone Assistant (Recommended)**
- Fully managed RAG — Pinecone handles chunking, embedding, and indexing automatically
- Built-in citations with file names and URLs
- Simpler setup: no embedding model or text splitter needed in n8n
- Great for: document Q&A, chat with files, knowledge base search

**Pinecone Vector Store**
- Full control over embedding model, chunking strategy, and metadata
- Works with any embedding model (OpenAI, Cohere, HuggingFace, etc.)
- Required when: you need custom embeddings, have an existing Pinecone index, need metadata filtering, or need fine-grained control over chunking

---

## Pinecone Assistant Node — Best Practices and Workflow Generation

### Node package names
- File operations (upload, list, delete): `@pinecone-database/n8n-nodes-pinecone-assistant.pineconeAssistant`
- Chat/retrieval as AI Agent tool: `@pinecone-database/n8n-nodes-pinecone-assistant.pineconeAssistantTool`

### Prerequisites
- Create a Pinecone Assistant in the Pinecone Console at https://app.pinecone.io/organizations/-/projects/-/assistant before running the workflow
- Set up a Pinecone credential in n8n with your API key

### Workflow architecture
The standard pattern is a two-phase workflow:

**Phase 1 — Ingestion** (run once or on a schedule):
```
Manual Trigger → Set file URLs → Split Out → HTTP Request (download) → Pinecone Assistant (uploadFile)
```

**Phase 2 — Chat**:
```
Chat Trigger → AI Agent ← Pinecone Assistant Tool (connected as ai_tool)
                        ← OpenAI Chat Model (connected as ai_languageModel)
```

### Key configuration rules
1. **assistantData parameter**: Always include BOTH `name` and `host` fields:
   ```json
   {"name": "your-assistant-name", "host": "https://your-assistant-host.pinecone.io"}
   ```
   Find your assistant's host in the Pinecone Console: open the assistant detail page and copy the host URL (format: `https://<region>-data.<subdomain>.pinecone.io`).
2. **sourceTag**: Always include in `additionalFields`:
   ```json
   {"sourceTag": "n8n:n8n_nodes_pinecone_assistant:pinecone_n8n_skill"}
   ```
3. **Connection type**: The Assistant Tool connects to the AI Agent via the `ai_tool` connection — NOT `main`
4. **externalFileId**: Set this to the file URL expression so Pinecone stores it as a reference for citations
5. **Credential**: Use `pineconeApi` credential type for both node variants
6. **File metadata on upload**: Add key-value metadata via `additionalFields.metadata.metadataValues` — an array of `{"key": "...", "value": "..."}` objects. The `externalFileId` is automatically added to metadata; do not include it manually. Example:
   ```json
   "additionalFields": {
     "metadata": {"metadataValues": [{"key": "department", "value": "legal"}]}
   }
   ```
7. **Metadata filtering on listFiles**: Use `additionalFields.metadataFilter.metadataValues` (same `{key, value}` array) for simple equality filters, or `additionalFields.advancedMetadataFilter` (a JSON string) for operators like `$or`, `$ne`, `$in`. Cannot set both at once. Example simple filter:
   ```json
   "additionalFields": {
     "metadataFilter": {"metadataValues": [{"key": "department", "value": "legal"}]}
   }
   ```
8. **Multimodal PDF upload**: Set `additionalFields.multimodalFile: true` on the `uploadFile` node when the PDF contains images or charts that should be indexed for visual retrieval. This is required for images to be retrievable later — it is not the default.

### Generating workflow JSON for the Assistant path

Build the workflow to match what the user actually describes — their triggers, models, data sources, and structure. Ask about anything structurally significant they haven't mentioned. Only fall back to the defaults below when the user hasn't specified a value:
- Assistant name: `n8n-assistant` (use `n8n-assistant-1`, `n8n-assistant-2`, etc. for multiples; must match an existing assistant in the Pinecone Console)
- File URLs: sample Pinecone release notes PDFs
- LLM model: `gpt-5-mini`
- System message: generic prompt about retrieving from the assistant with citations

The JSON below is a **reference configuration** showing correct parameter values, required fields, and connection types for each node. Use it as a guide for how to configure the nodes — not as a template to copy verbatim. Placeholders to substitute:
- `[ASSISTANT_NAME]` — assistant name
- `[ASSISTANT_HOST]` — assistant host URL from the Pinecone Console (e.g. `https://your-assistant-host.pinecone.io`)
- `[USER_FILE_URLS_ARRAY]` — JSON array of file URL strings, e.g. `["https://example.com/doc.pdf"]`
- `[USER_MODEL]` — LLM model name, e.g. `gpt-5-mini`
- `[USER_TOPIC]` — short description of what the assistant knows, for the system message

```json
{
  "nodes": [
    {
      "parameters": {
        "options": {
          "systemMessage": "You are a helpful assistant. Use the Pinecone Assistant Tool to retrieve data about [USER_TOPIC]. Include the file name and file url in citations wherever referenced in output."
        }
      },
      "type": "@n8n/n8n-nodes-langchain.agent",
      "typeVersion": 2.2,
      "position": [2208, 784],
      "id": "e4c65881-120c-4a7c-854b-138611c8dfa3",
      "name": "AI Agent"
    },
    {
      "parameters": {
        "model": {"__rl": true, "mode": "list", "value": "[USER_MODEL]"},
        "options": {}
      },
      "type": "@n8n/n8n-nodes-langchain.lmChatOpenAi",
      "typeVersion": 1.2,
      "position": [2144, 1008],
      "id": "b3ea858d-b62d-4022-8241-8872e403839a",
      "name": "OpenAI Chat Model"
    },
    {
      "parameters": {
        "content": "## 1. Upload files to Pinecone Assistant",
        "height": 384,
        "width": 1104,
        "color": 7
      },
      "type": "n8n-nodes-base.stickyNote",
      "position": [1616, 288],
      "typeVersion": 1,
      "id": "9cfcdb71-2986-47a3-8f03-250fcab1048d",
      "name": "Sticky Note1"
    },
    {
      "parameters": {
        "content": "## 2. Chat with your docs",
        "height": 512,
        "width": 1104,
        "color": 7
      },
      "type": "n8n-nodes-base.stickyNote",
      "position": [1616, 688],
      "typeVersion": 1,
      "id": "d7f2f4b8-2e45-4902-8949-202b8b2c699b",
      "name": "Sticky Note2"
    },
    {
      "parameters": {"o