Advanced Entity Search

Introduction

The Sayari Search API provides powerful search capabilities through Lucene Query Syntax. This guide will help you construct effective queries, from basic searches to complex combinations of search techniques.

Getting Started

1
{
2
  "q": "Your lucene query here",
3
  "filter": {
4
    // Additional filters
5
  },
6
  "advanced": true
7
}

1
{
2
  "q": "(name.value:Apple OR identifier.value: 0796001839)",
3
  "filter":
4
  {
5
    "entity_type": ["company"],
6
    "country": ["USA"]
7
  },
8
  "advanced": true
9
}

1
curl -X POST "https://api.sayari.com/v1/search/entity" \
2
     -H "Authorization: Bearer <token>" \
3
     -H "Content-Type: application/json" \
4
     -d '{
5
  "q": "(name.value:Apple OR identifier.value: 0796001839)",
6
  "filter": {
7
    "entity_type": ["company"],
8
    "country": ["USA"]
9
  },
10
  "advanced": true
11
}'

Term Modifiers

Boolean Operators

1
{
2
  "q": "(name.value:Apple AND address.value:Cupertino)",
3
  "filter": {
4
    "entity_type": ["company"],
5
    "country": ["USA"]
6
  },
7
  "advanced": true
8
}

This query demonstrates the use of the boolean AND operator to combine multiple search conditions. Boolean operators must be uppercase (AND, OR) and allow you to create logical relationships between search terms:

• AND: Requires both conditions to be true
• OR: Requires at least one condition to be true, alternatively a pipe | can be utilized.
• NOT: Excludes matches that meet the condition

The example finds companies that must have both “Apple” in their name AND “Cupertino” in their address, filtered to only include USA-based companies.

Exact Terms (Quotation Marks)

1
{
2
  "q": "name.value:\"Green Apple\"",
3
  "filter": {
4
    "entity_type": ["company"],
5
    "country": ["USA"]
6
  },
7
  "advanced": true
8
}

This query uses quotation marks (" ") to search for an exact match of “Green Apple” as a term in the company name. Filters are utilized to only include matches that include companies with a country context in the USA.

Excluding Terms (Hyphen)

1
{
2
  "q": "-name.value:\"Green\" AND name.value:\"Apple\"",
3
  "filter": {
4
    "entity_type": ["company"]
5
  },
6
  "advanced": true
7
}

This query uses a hyphen (-) to exclude the term “Green” and the AND operator to require “Apple”, searching for company entities that do not have “Green” but do have the exact term “Apple” in their name. Please note, the hyphen is applied to the field, not the value.

Fuzzy Search (Tilde)

1
{
2
  "q": "name.value:Aple~2 AND name.value:Green",
3
  "filter": {
4
    "entity_type": ["company"]
5
  },
6
  "advanced": true
7
}

This query uses the tilde (~) followed by a number to perform a fuzzy search, finding companies with names similar to “Apple”, allowing for up to 2 character differences. It’s combined with an exact match for “Green”.

Boosted Terms Search (Caret)

1
{
2
  "q": "name.value:Green^4 AND name.value:Apple",
3
  "filter": {
4
    "entity_type": ["company"]
5
  },
6
  "advanced": true
7
}

This query uses the caret (^) followed by a number to boost the term “Green”, giving it higher relevance in the search results. It’s combined with a regular search for “Apple”.

Grouping and Field Grouping (Parentheses)

1
{
2
  "q": "(name.value:\"Apple\") AND (address.value:Cupertino) AND (identifier.value:549300GF4NZMYB9VP153)",
3
  "filter": {
4
    "entity_type": ["company"],
5
    "country": ["USA"]
6
  },
7
  "advanced": true
8
}

This query uses boolean operators to find companies that must have “Apple” in the name, “Cupertino” in the address AND “549300GF4NZMYB9VP153” as an identifier. This can help narrow does to specific attributes.

Complex Query Combining Multiple Techniques

1
{
2
  "q": "(name.value:\"Apple\"^4 AND address.value:\"Cupertino\"^2) OR (identifier.value:\"549300GF4NZMYB9VP153\" AND business_purpose.value:\"technology\"~4)",
3
  "filter": {
4
    "entity_type": ["company"],
5
    "country": ["USA"]
6
  },
7
  "advanced": true
8
}

This query demonstrates how to combine multiple search techniques (Quotation Marks, Boosting, Fuzzy Search, Grouping) to create a precise search. The query prioritizes companies named “Apple” in “Cupertino”, while also allowing for an alternate search path using a specific identifier and approximate business purpose matching.