Skip to main content
New projects should use the Documents API. To move an existing index, see Move to the Documents API.
This page shows you how to search a legacy integrated index created with create_index_for_model. The legacy Records API converts the query text to a vector with the embedding model associated with the index. For a document index with integrated embedding, see Semantic search and Sparse-vector search.

Search with dense embedding

To search a legacy integrated index with query text, use the Search with text operation with the following parameters:
  • The namespace to query. To use the default namespace, set the namespace to "__default__".
  • The query.inputs.text parameter with the query text. Pinecone uses the embedding model integrated with the index to convert the text to a dense vector automatically.
  • The query.top_k parameter with the number of similar records to return.
  • Optionally, the fields to return in the response. If you don’t specify any, the response includes all fields.
For example, the following code searches for the 2 records most semantically related to the query text “Disease prevention”:
In the response, each record has a similarity score that represents its distance to the query vector, calculated according to the index’s similarity metric:

Search with sparse embedding

To search a legacy integrated index with query text, use the Search with text operation with the following parameters:
  • namespace: The namespace to query. To use the default namespace, set to "__default__".
  • query.inputs.text: The query text. Pinecone uses the embedding model integrated with the index to convert the text to a sparse vector automatically.
  • query.top_k: The number of records to return.
  • query.match_terms: (Optional) A list of terms that must be present in each search result. For more details, see Filter by required terms.
  • fields: (Optional) The fields to return in the response. If not specified, the response includes all fields.
For example, the following code converts the query “What is AAPL’s outlook, considering both product launches and market conditions?” to a sparse vector and then searches for the 3 most similar vectors in the example-namespace namespace:
The results look like this. The most similar records are scored highest.

Filter by required terms

This feature is in public preview. See limitations for details.
When searching a legacy integrated index with text, you can specify a list of terms that must be present in each sparse-vector search result. This is especially useful for:
  • Precision filtering: Ensuring specific entities or concepts appear in results
  • Quality control: Filtering out results that don’t contain essential keywords
  • Domain-specific searches: Requiring domain-specific terminology in results
  • Entity-based filtering: Ensuring specific people, places, or things are mentioned
To filter by required terms, add match_terms to your query, specifying the terms to require and the strategy to use. all is the only supported strategy: every term must be present. For example, the following request searches for records about Tesla’s stock performance while ensuring both “Tesla” and “stock” appear in each result:
curl
The response includes only records that contain both “Tesla” and “stock”:
Without the match_terms filter, you might get results like:
  • “Tesla cars are popular in California” (mentions Tesla but not stock)
  • “Stock market volatility affects tech companies” (mentions stock but not Tesla)
  • “Electric vehicle sales are growing” (neither Tesla nor stock)

Limitations

  • Legacy integrated indexes only: Filtering by required terms is supported only for legacy integrated indexes that use pinecone-sparse-english-v0. In a document index, use a $match_all filter instead.
  • Post-processing filter: The filtering happens after the initial query, so potential matches that weren’t included in the initial top_k results won’t appear in the final results.
  • No phrase matching: Terms are matched individually in any order and location.
  • No case-sensitivity: Terms are normalized during processing.

Search with a metadata filter

The following code searches for the 3 records that are most semantically similar to a query and that have a category metadata field with the value digestive system. For the supported operators, see Metadata filter expressions.