List or Describe Indexes

Lists all indexes in your Pinecone project or retrieves detailed information about a specific index. This node combines two operations controlled by the Method option.

Common Properties

• Name - The custom name of the node.
• Color - The custom color of the node.
• Delay Before (sec) - Waits in seconds before executing the node.
• Delay After (sec) - Waits in seconds after executing node.
• Continue On Error - Automation will continue regardless of any error. The default value is false.

info

If the ContinueOnError property is true, no error is caught when the project is executed, even if a Catch node is used.

Inputs

• Connection Id - Connection identifier from Connect node (optional if API Key credential is provided directly).
• Environment - Your Pinecone environment (e.g., us-east-1-aws, us-west1-gcp, eu-west1-gcp). You can find this in your Pinecone console.
• Index Name - Name of the index to describe. Required only when Method is set to "Describe Index".

Options

• API Key - Pinecone API key credential (optional - use this instead of Connection Id if not using Connect node).
• Method - Choose the operation to perform:
  • List Indexes - Returns a list of all indexes in your project
  • Describe Index - Returns detailed information about a specific index

Output

• Response - Object containing either a list of indexes or details about a specific index, depending on the Method.

List Indexes Response

[
  "index-1",
  "index-2",
  "documents-ada002"
]

Describe Index Response

{
  "database": {
    "name": "documents-ada002",
    "dimension": 1536,
    "metric": "cosine",
    "pods": 1,
    "replicas": 1,
    "shards": 1,
    "podType": "p1.x1"
  },
  "status": {
    "ready": true,
    "state": "Ready"
  }
}

How It Works

The List or Describe Indexes node retrieves index information from Pinecone. When executed, the node:

1. Validates required inputs (Environment, and Index Name if using Describe Index)
2. Constructs the appropriate API endpoint based on the Method
3. Sends a GET request to Pinecone's controller API
4. Returns either a list of index names or detailed index information

Requirements

• A valid Pinecone account and API key
• Valid environment identifier
• For Describe Index: a valid index name

Error Handling

The node will return specific errors in the following cases:

• ErrInvalidArg - Environment is empty
• ErrInvalidArg - Index Name is empty (when using Describe Index method)
• ErrInvalidArg - Invalid Connection ID or missing API key
• ErrInternal - Response format is not valid
• ErrStatus - HTTP error from Pinecone API (invalid environment, index not found, etc.)

Usage Notes

• List Indexes returns an array of index name strings
• Describe Index returns detailed configuration and status
• The status.ready field indicates if the index is ready for operations
• Newly created indexes may show ready: false until initialization completes
• This operation does not consume query quota

Index Status Values

When using Describe Index, the status can be:

• Ready - Index is fully operational
• Initializing - Index is being created
• ScalingUp / ScalingDown - Index is being scaled
• Terminating - Index is being deleted

Best Practices

• Use List Indexes to discover available indexes programmatically
• Use Describe Index to verify index configuration before operations
• Check status.ready before performing data operations
• Store index details for reference in your automation
• Use this to validate index existence before creating a new one

Example: List All Indexes

// Configure node:
// Method: List Indexes
// Environment: us-east-1-aws

// After execution
const indexes = msg.resListorDescribe;

console.log(`Found ${indexes.length} indexes:`);
indexes.forEach(indexName => {
  console.log(`- ${indexName}`);
});

// Store for later use
msg.availableIndexes = indexes;

Example: Check Index Configuration

// Configure node:
// Method: Describe Index
// Environment: us-east-1-aws
// Index Name: documents-ada002

// After execution
const indexInfo = msg.resListorDescribe;
const db = indexInfo.database;

console.log("Index Configuration:");
console.log(`  Name: ${db.name}`);
console.log(`  Dimension: ${db.dimension}`);
console.log(`  Metric: ${db.metric}`);
console.log(`  Pods: ${db.pods}`);
console.log(`  Replicas: ${db.replicas}`);
console.log(`  Pod Type: ${db.podType}`);
console.log(`  Status: ${indexInfo.status.state}`);
console.log(`  Ready: ${indexInfo.status.ready}`);

Example: Wait for Index to Be Ready

// After creating an index, wait for it to be ready
const MAX_ATTEMPTS = 30;
const DELAY_SECONDS = 10;

for (let i = 0; i < MAX_ATTEMPTS; i++) {
  // Use Describe Index node
  const indexInfo = msg.resListorDescribe;

  if (indexInfo.status.ready) {
    console.log(`✓ Index is ready after ${i * DELAY_SECONDS} seconds`);
    break;
  }

  console.log(`Waiting for index... (${i + 1}/${MAX_ATTEMPTS})`);

  if (i < MAX_ATTEMPTS - 1) {
    // Wait before next check (use Delay node)
    await sleep(DELAY_SECONDS * 1000);
  }
}

if (!msg.resListorDescribe.status.ready) {
  throw new Error("Index did not become ready in time");
}

Example: Validate Index Before Operations

// Before upserting data, verify index configuration
const indexInfo = msg.resListorDescribe;
const db = indexInfo.database;

// Check if ready
if (!indexInfo.status.ready) {
  throw new Error(`Index is not ready. Status: ${indexInfo.status.state}`);
}

// Verify dimension matches embeddings
const expectedDimension = 1536; // OpenAI ada-002
if (db.dimension !== expectedDimension) {
  throw new Error(`Dimension mismatch: Index has ${db.dimension}, expected ${expectedDimension}`);
}

// Verify metric
if (db.metric !== "cosine") {
  console.warn(`Index uses ${db.metric} metric instead of cosine`);
}

console.log("✓ Index validation passed");

Example: Check if Index Exists

// Step 1: List all indexes
const allIndexes = msg.resListorDescribe;
const indexName = "my-new-index";

if (allIndexes.includes(indexName)) {
  console.log(`Index '${indexName}' already exists`);
  msg.shouldCreateIndex = false;
} else {
  console.log(`Index '${indexName}' does not exist`);
  msg.shouldCreateIndex = true;
}

// Use this flag to conditionally create the index

Example: Index Inventory Report

// Step 1: List Indexes to get all names
const indexNames = msg.resListorDescribe;

// Step 2: Loop through and describe each
const inventory = [];

for (const indexName of indexNames) {
  // Configure Describe Index for each index
  // (In practice, you'd need multiple Describe Index nodes or a loop)

  const indexInfo = msg.resListorDescribe;
  const db = indexInfo.database;

  inventory.push({
    name: db.name,
    dimension: db.dimension,
    metric: db.metric,
    pods: db.pods,
    replicas: db.replicas,
    podType: db.podType,
    ready: indexInfo.status.ready,
    state: indexInfo.status.state
  });
}

console.log("Index Inventory:");
console.table(inventory);

msg.indexInventory = inventory;

Example: Calculate Total Resources

// After getting all index details
const inventory = msg.indexInventory;

const totalResources = inventory.reduce((acc, index) => {
  return {
    totalPods: acc.totalPods + index.pods,
    totalReplicas: acc.totalReplicas + index.replicas,
    indexes: acc.indexes + 1
  };
}, { totalPods: 0, totalReplicas: 0, indexes: 0 });

console.log(`Total Resources:`);
console.log(`  Indexes: ${totalResources.indexes}`);
console.log(`  Total Pods: ${totalResources.totalPods}`);
console.log(`  Total Replicas: ${totalResources.totalReplicas}`);

Example: Find Indexes by Configuration

// Find all indexes using cosine metric
const allIndexes = msg.resListorDescribe;

// You'd need to describe each index to get this info
const cosineIndexes = msg.indexInventory.filter(index =>
  index.metric === "cosine"
);

console.log(`Found ${cosineIndexes.length} indexes using cosine metric:`);
cosineIndexes.forEach(index => {
  console.log(`- ${index.name} (${index.dimension}D, ${index.pods} pods)`);
});

Example: Pre-Create Validation

// Before creating a new index, check if name is available
const indexName = msg.newIndexName;

// Use List Indexes
const existingIndexes = msg.resListorDescribe;

if (existingIndexes.includes(indexName)) {
  throw new Error(`Index name '${indexName}' is already taken`);
}

// Check environment is valid (you'd have a list of valid environments)
const validEnvironments = [
  "us-east-1-aws",
  "us-west1-gcp",
  "eu-west1-gcp"
];

if (!validEnvironments.includes(msg.environment)) {
  throw new Error(`Invalid environment: ${msg.environment}`);
}

console.log("✓ Pre-create validation passed");

Example: Monitor Index States

// Get all indexes and their states
const inventory = msg.indexInventory;

const stateGroups = inventory.reduce((acc, index) => {
  const state = index.state;
  if (!acc[state]) acc[state] = [];
  acc[state].push(index.name);
  return acc;
}, {});

console.log("Index States:");
Object.entries(stateGroups).forEach(([state, indexes]) => {
  console.log(`  ${state}: ${indexes.length} indexes`);
  indexes.forEach(name => console.log(`    - ${name}`));
});

// Alert if any indexes are not ready
const notReady = inventory.filter(i => !i.ready);
if (notReady.length > 0) {
  console.warn(`⚠ ${notReady.length} indexes are not ready:`, notReady.map(i => i.name));
}

Example: Get Host URL from Index Info

// Use Describe Index to get the host URL
const indexInfo = msg.resListorDescribe;
const indexName = indexInfo.database.name;

// You'll need to know your project ID from Pinecone console
const projectId = msg.pineconeProjectId;
const environment = msg.environment;

// Construct host URL
const hostUrl = `https://${indexName}-${projectId}.svc.${environment}.pinecone.io`;

console.log(`Host URL: ${hostUrl}`);
msg.hostUrl = hostUrl;

// Use this for subsequent operations (Upsert, Query, etc.)

Troubleshooting

Error: "Environment cannot be empty"

• Provide a valid Pinecone environment
• Check that the environment variable/input is set correctly
• Verify the environment string (e.g., "us-east-1-aws")

Error: "Index Name cannot be empty"

• This occurs when using Describe Index method
• Ensure Index Name input is provided
• Check that the variable reference is correct

Index not found

• Verify the index name is correct (case-sensitive)
• Check that you're using the correct environment
• Use List Indexes to see available indexes

Empty list returned

• No indexes exist in your project
• Wrong environment specified
• API key may not have access to indexes

Index shows ready: false

• Index is still initializing (newly created)
• Index is being scaled or modified
• Wait and check again in a few minutes
• Check status.state for more details

Different environments have different indexes

• Indexes are environment-specific
• Ensure you're querying the correct environment
• List indexes for each environment separately