Skip to main content

Searching

For performing a part-search, the Partium-SDK provides one main search-function, which you can call via:

Partium.search.performSearch();

To start a new search, call performSearch with the name of the organization you want to search in and the desired search language. You will send this information together with the search-input that should be used for searching.

Partium.search.performSearch(
  {
    organizationName: '<organization-name>',  // e.g.: 'Partium' (get this from your Partium contact person)
    searchLanguage: '<search-language-code>',  // e.g.: 'en'
    text: 'valve',
  }
).subscribe((result: SearchOutput) => {
  // search successful, find results in result.searchResults
}, (error: SdkError) => {
  // an error happened during the search
});

SearchInput​

The SearchInput-object is the main input for a search and contains all the necessary information for starting a new search or to continue a previous search.

interface SearchInput {
  organizationName: string; // the organization name
  searchLanguage: string; // the search language
  searchSessionId?: string;  // id of an existing search-session, to continue the session

  // search modalities:
  text?: string;  // text search
  searchImageAssetId?: string; //  image search via asset-id
  searchImage?: PFile;  // image search via file
  searchImageCropArea?: ImageCropArea;  // image search crop area
  hierarchyFilters?: string[];  // filter search via hierarchy filter
  attributeFilters?: Record<string, string[]>;  // filter search via attribute filter
}

A search needs at least input for one of the available search modalities. It is also possible to use multiple modalities at the same time, to refine the search results. Learn more about the different search modalities here.

SearchOutput​

The response of a performSearch call is of type SearchOutput. Besides the actual search results, it contains the search input that you passed. This object also contains the searchSessionId. The SearchOutput also contains the proposed smart filters, that should be provided to the user (learn more about smart filters).

export interface SearchOutput {
  searchInput: ResponseSearchInput; // the search input that lead to this output, including the searchSessionId of that search session
  searchResults: Part[];  // the actual search result
  smartFilters: SmartFilter[];  // the proposed smart filters
}

Search sessions - continue a search​

To continue a search session that you started with a previous request, you can use the searchSessionId. It can be found inside any SearchOutput-object returned by performSearch. You can pass it to your next call of performSearch, along with the updated search input. The searchSessionId stays the same for an entire search session.

Partium.search.performSearch(
  {
    organizationName: '<organization-name>',  // must be the same as in the initial call of performSearch
    searchLanguage: '<search-language-code>',  // must be the same as in the initial call of performSearch
    searchSessionId: '<search-session-id>',  // from the SearchOutput of a previous search
    text: 'gate valve',
  }
).subscribe((result: SearchOutput) => {
  // search successful
}, (error: SdkError) => {
  // an error happened during the search
});

Despite the different searchSessionId, you would not see any difference in the search results, independent if you start a new search session, or continue a previous one. The big benefit of continuous search sessions is that it allows you to keep track of the user flow during his search journey. This will be of significant importance when viewing the analytics or logs.

If you want to start a new search, just call performSearch without the searchSessionId.

info

Use the searchSessionId to connect multiple calls of performSearch to a continuous search session.

Loading existing search sessions​

You can also load the results and state of an existing search session using the getSearchOutput() method. This is useful for:

  • Loading more results from a previous search (pagination)
  • Restoring a search session after a page reload
  • Accessing search results from a different part of your application
// Load existing search session data
Partium.search.getSearchOutput(
  '<search-session-id>', // The searchSessionId from a previous search
  ['results.id', 'results.partiumId', 'results.name', 'results.images'], // projection (optional)
  { limit: 25, skip: 0 } // resultOptions (optional)
).subscribe((searchOutput: SearchOutput) => {
  // Access the search results and input
  console.log('Loaded search results:', searchOutput.searchResults);
  console.log('Original search input:', searchOutput.searchInput);
  console.log('Total results available:', searchOutput.resultsTotalCount);
}, (error: SdkError) => {
  // Handle errors (e.g., session not found or expired)
  console.error('Failed to load search session:', error);
});

The getSearchOutput() method accepts the following parameters:

  • searchSessionId (string): The ID of the search session to load
  • projection (string[], optional): Array specifying which data fields to include in the response
  • resultOptions (object, optional): Options for result pagination and filtering
    • limit: Maximum number of results to return (default: 25)
    • skip: Number of results to skip for pagination (default: 0)

Search flow example​

An important aspect of a search session is that all search input needs to be sent with every request, not just the search input that changed. So if the user starts with a text search in the first request and later adds an attribute filter to the search, the text search query needs to be sent again with the second request.

Here is an example search flow, where the user

  1. starts a new search session with a text search query
  2. adds a search image to the search session
  3. applies a hierarchy filter and an attribute filter
  4. changes the text of the search query
  5. remove text search
let searchSessionId = null;    // used to continue a search session over multiple requests
let searchImageAssetId = null; // used to keep the same search image over multiple requests

// 1 - user starts text search
Partium.search.performSearch(
  {
    organizationName: 'Partium',
    searchLanguage: 'en',
    text: 'EX3',
  }
).subscribe((searchOutput: SearchOutput) => {
  searchSessionId = searchOutput.searchInput.searchSessionId;
});

...

// 2 - add search image
Partium.search.performSearch(
  {
    organizationName: 'Partium',
    searchLanguage: 'en',
    searchSessionId: searchSessionId,
    text: 'EX3',
    searchImage: new JsPFile( imageBlob ),
    searchImageCropArea: { x1: 0.1, y1: 0.2, x2: 0.5, y2: 0.8 },
  }
).subscribe((searchOutput: SearchOutput) => {
  searchImageAssetId = searchOutput.searchInput.searchImageAssetId;
});

...

// 3 - add hierarchy- and attribute filter
Partium.search.performSearch(
  {
    organizationName: 'Partium',
    searchLanguage: 'en',
    searchSessionId: searchSessionId,
    text: 'EX3',
    searchImageAssetId: searchImageAssetId,
    searchImageCropArea: { x1: 0.1, y1: 0.2, x2: 0.5, y2: 0.8 },
    hierarchyFilters: ['1ec55a3b-2408-4ed8-8e83-c3a88d0e7b86', '19f8a7e3-a3b5-450d-bd1f-14114bf53cd7'],
    attributeFilters: {
      [ 'Category' ]: [ 'Fan', 'Connector' ],
      [ 'Voltage' ]: [ '20V' ],
    },
  }
)

...

// 4 - text search query change
Partium.search.performSearch(
  {
    organizationName: 'Partium',
    searchLanguage: 'en',
    searchSessionId: searchSessionId,
    text: '45Q231_L',
    searchImageAssetId: searchImageAssetId,
    searchImageCropArea: { x1: 0.1, y1: 0.2, x2: 0.5, y2: 0.8 },
    hierarchyFilters: ['1ec55a3b-2408-4ed8-8e83-c3a88d0e7b86', '19f8a7e3-a3b5-450d-bd1f-14114bf53cd7'],
    attributeFilters: {
      [ 'Category' ]: [ 'Fan', 'Connector' ],
      [ 'Voltage' ]: [ '20V' ],
    },
  }
)

...

// 5 - remove text search
Partium.search.performSearch(
  {
    organizationName: 'Partium',
    searchLanguage: 'en',
    searchSessionId: searchSessionId,
    searchImageAssetId: searchImageAssetId,
    searchImageCropArea: { x1: 0.1, y1: 0.2, x2: 0.5, y2: 0.8 },
    hierarchyFilters: ['1ec55a3b-2408-4ed8-8e83-c3a88d0e7b86', '19f8a7e3-a3b5-450d-bd1f-14114bf53cd7'],
    attributeFilters: {
      [ 'Category' ]: [ 'Fan', 'Connector' ],
      [ 'Voltage' ]: [ '20V' ],
    },
  }
)

Handling Large Result Sets​

When working with searches that return many results, you'll want to implement pagination to provide a good user experience. The Partium SDK provides built-in pagination support through the resultOptions parameter.

For detailed information about implementing pagination, including "load more" functionality and best practices, see the Pagination section.

// Example: Load first 50 results instead of default 25
Partium.search.performSearch(
  {
    organizationName: 'Partium',
    searchLanguage: 'en',
    text: 'valve',
  },
  undefined, // searchEventContext
  undefined, // projection
  {
    limit: 50, // Increase page size
  },
);