CorvidReference

WixSearchBuilder

Contains functionality for refining a site search.

The WixSearchBuilder functions enable you to run, filter, and control which results a search returns.

Typically, you build a search using the search() function, refine the search by chaining WixSearchBuilder functions, and then execute the search by chaining a find() function.

For example, the following searches a site for all products containing the phrase "shoe" in English in the Stores/Products collection and logs the first 5 results to the console:

 import wixSearch from 'wix-search';

 wixSearch.search("shoe")
   .language("en")
   .documentType("Stores/Products")
   .limit(5)
   .find()
   .then( (results) => {
     console.log(results.documents);
   } );

Table of Contents

FUNCTIONS

?
Perform actions on an object.
documentType( )Refines a search builder to only search for documents of the specified document type.
find( )Returns the documents that match the search.
language( )Refines a search builder to search in the specified language.
limit( )Limits the number of documents the search returns.
skip( )Sets the number of documents to skip before returning search results.

documentType( )

Refines a search builder to only search for documents of the specified document type.

Description

The document type can be one of the following:

  • Site/Pages
  • Blog/Posts
  • Bookings/Services
  • Forum/Posts
  • Stores/Products

By default, the search includes all document types.

Setting the document type to Site/Pages restricts the search to all regular pages that have SEO indexing enabled. Note that all Wix site pages are indexed by default. Dynamic pages, custom router pages, and some Wix app pages are not currently included in the search.

Setting the document type to a Wix app collection restricts the search to items in the specified collection.

You cannot chain multiple documentType() functions to search for multiple document types. Only the last specified document type will be searched.

Syntax

function documentType(type: string): WixSearchBuilder
PARAMETERS
?
Values that you pass to a function.
type
string
The document type to search in.
RETURN VALUE
?
Value that a function evaluates to when it is finished running.
A WixSearchBuilder object representing the refined search.

Examples

Add a document type filter to a search

let newSearch = search.documentType("Site/Pages");

Create a search, add a document type filter, and run it

import wixSearch from 'wix-search';

// ...

$w("#searchInput").onKeyPress((keyPress) => {
  if (keyPress.key === "Enter") {
    const phrase = $w("#searchInput").value;
    wixSearch.search(phrase)
      .documentType("Stores/Products")
      .find()
      .then( (results) => {
        if(results.documents.length > 0) {
          let documents = results.documents;
        } else {
          console.log("No matching results");
        }
      })
      .catch( (error) => {
        console.log(error);
      });
  }
});

Build and run a search and display the results in a repeater

This example demonstrates how to set up a search for store products and display the results in a repeater. Each button in the repeater links to the product page for the selected product.
import wixSearch from 'wix-search';

// ...

// Before search runs, set the repeater data as empty
$w('#repeater').data = [];

$w("#searchInput").onKeyPress((keyPress) => {
  if (keyPress.key === "Enter") {
    const phrase = $w("#searchInput").value;
    wixSearch.search(phrase)
      .documentType("Stores/Products")
      .find()
      .then((results) => {
        if (results.documents.length > 0) {
          $w('#repeater').data = results.documents;
        } else {
          console.log("No matching results");
        }
      })
      .catch((error) => {
        console.log(error);
      });
  }
});

$w("#repeater").onItemReady(($item, itemData) => {
  $item("#title").text = itemData.title;
  $item("#description").text = itemData.description;
  $item("#image").src = itemData.image;
  $item("#button").link = itemData.url;
});

find( )

Returns the documents that match the search.

Description

The find() function returns a Promise that resolves to the results found by the search and some information about the results. The Promise is rejected if any of the functions used to refine the search are invalid.

If you build a search and don't refine it with any WixSearchBuilder functions, find() returns all matching site documents.

Syntax

function find(): Promise<WixSearchResult>
RETURN VALUE
?
Value that a function evaluates to when it is finished running.

Fulfilled - A Promise that resolves to the results of the search. Rejected - Error that caused the search to fail.

Examples

Perform a find on a search

This example demonstrates how to run a find() on a search() that was previously built and stored in a variable.
search.find()
  .then((results) => {
    if (results.documents.length > 0) {
      let documents = results.documents;
    } else {
      console.log("No matching results");
    }
  })
  .catch((error) => {
    console.log(error);
  });

Create a search and run it

This example demonstrates how to build a search() and then run a find() on it.
import wixSearch from 'wix-search';

// ...

$w("#searchInput").onKeyPress((keyPress) => {
  if (keyPress.key === "Enter") {
    const phrase = $w("#searchInput").value;
    wixSearch.search(phrase)
      .find()
      .then((results) => {
        if (results.documents.length > 0) {
          let documents = results.documents;
        } else {
          console.log("No matching results");
        }
      })
      .catch((error) => {
        console.log(error);
      });
  }
});

Create a search, add functions to the search, and run it

This example demonstrates how to build a search(), chain additional functions such as language() and limit() to the search, and then run the search().
import wixSearch from 'wix-search';

// ...

$w("#searchInput").onKeyPress((keyPress) => {
  if (keyPress.key === "Enter") {
    const phrase = $w("#searchInput").value;
    wixSearch.search(phrase)
      .language("ja") // Japanese
      .documentType("Bookings/Services")
      .limit(10)
      .find()
      .then((results) => {
        if (results.documents.length > 0) {
          let documents = results.documents;
        } else {
          console.log("No matching results");
        }
      })
      .catch((error) => {
        console.log(error);
      });
  }
});

Build and run a search and display the results in a repeater

This example demonstrates how to set up a search for store products and display the results in a repeater. Each button in the repeater links to the product page for the selected product.
import wixSearch from 'wix-search';

// ...

// Before search runs, set the repeater data as empty
$w('#repeater').data = [];

$w("#searchInput").onKeyPress((keyPress) => {
  if (keyPress.key === "Enter") {
    const phrase = $w("#searchInput").value;
    wixSearch.search(phrase)
      .documentType("Stores/Products")
      .find()
      .then((results) => {
        if (results.documents.length > 0) {
          $w('#repeater').data = results.documents;
        } else {
          console.log("No matching results");
        }
      })
      .catch((error) => {
        console.log(error);
      });
  }
});

$w("#repeater").onItemReady(($item, itemData) => {
  $item("#title").text = itemData.title;
  $item("#description").text = itemData.description;
  $item("#image").src = itemData.image;
  $item("#button").link = itemData.url;
});

language( )

Refines a search builder to search in the specified language.

Description

The value of the search language must be a two-letter language code string of ISO 639-1 format.

Defaults for language:

Syntax

function language(language: string): WixSearchBuilder
PARAMETERS
?
Values that you pass to a function.
language
string
The search language.
RETURN VALUE
?
Value that a function evaluates to when it is finished running.
A WixSearchBuilder object representing the refined search.

Examples

Add a language filter to a search

let newSearch = search.language("fr"); // French

Create a search, add a language filter, and run it

import wixSearch from 'wix-search';

// ...

$w("#searchInput").onKeyPress((keyPress) => {
  if (keyPress.key === "Enter") {
    const phrase = $w("#searchInput").value;
    wixSearch.search(phrase)
      .language("pt") // Portuguese
      .find()
      .then((results) => {
        if (results.documents.length > 0) {
          let documents = results.documents;
        } else {
          console.log("No matching results");
        }
      })
      .catch((error) => {
        console.log(error);
      });
  }
});

limit( )

Limits the number of documents the search returns.

Description

The limit() function defines the number of results a search returns in each page. Only one page of results is retrieved at a time. The next() and prev() functions are used to navigate the pages of a search result.

By default, limit is set to 25.

The maximum value that limit() can accept is 1000.

Syntax

function limit(limit: number): WixSearchBuilder
PARAMETERS
?
Values that you pass to a function.
limit
number
The number of documents to return, which is also the pageSize of the results object.
RETURN VALUE
?
Value that a function evaluates to when it is finished running.
A WixSearchBuilder object representing the refined search.

Examples

Add a limit to a search

let newSearch = search.limit(10);

Create a search, add a limit, and run it

import wixSearch from 'wix-search';

// ...

$w("#searchInput").onKeyPress((keyPress) => {
  if (keyPress.key === "Enter") {
    const phrase = $w("#searchInput").value;
    wixSearch.search(phrase)
      .limit(10)
      .find()
      .then((results) => {
        if (results.documents.length > 0) {
          let documents = results.documents;
        } else {
          console.log("No matching results");
        }
      })
      .catch((error) => {
        console.log(error);
      });
  }
});

Iterate through all pages of search results

This example demonstrates how to get all search results, bypassing the maximum limit of 1000.
async function retrieveAllDocuments(phrase){
  let allDocuments = [];
    
  let results = await wixSearch.search(phrase)
    .limit(1000)
    .find();
    
  allDocuments.push(results.documents);
    
  while(results.hasNext()) {
    results = await results.next();
    allDocuments.push(results.documents);
  }
    
  return allDocuments;
}

skip( )

Sets the number of documents to skip before returning search results.

Description

The skip() function defines the number of results to skip in the search results before returning new search results.

For example, if you search your site and 20 documents match your search, but you set skip to 5, the results returned will skip the first 5 documents that match and return the 6th through 20th documents.

By default, skip is set to 0.

The maximum value that skip() can accept is 100000.

Syntax

function skip(skip: number): WixSearchBuilder
PARAMETERS
?
Values that you pass to a function.
skip
number
The number of documents to skip in the search results before returning the results.
RETURN VALUE
?
Value that a function evaluates to when it is finished running.
A WixSearchBuilder object representing the refined search.

Examples

Add a skip to a search

let newSearch = search.skip(10);

Create a search, add a skip, and run it

import wixSearch from 'wix-search';

// ...

$w("#searchInput").onKeyPress((keyPress) => {
  if (keyPress.key === "Enter") {
    const phrase = $w("#searchInput").value;
    wixSearch.search(phrase)
      .skip(10)
      .find()
      .then((results) => {
        if (results.documents.length > 0) {
          let documents = results.documents;
        } else {
          console.log("No matching results");
        }
      })
      .catch((error) => {
        console.log(error);
      });
  }
});