Pagination

The Partium Find SDK provides built-in pagination support to help you efficiently manage large result sets. This is particularly useful when dealing with searches that return hundreds or thousands of parts.

Overview

Pagination in the Find SDK works through two main mechanisms:

1. Initial search pagination - Control how many results are returned with the first search
2. Load more results - Fetch additional pages of results from an existing search session

Both performSearch() and getSearchOutput() methods support pagination through resultOptions parameters like skip and limit. See the API Reference section for detailed method comparisons.

Basic Pagination

Controlling Initial Results

When performing a search with performSearch(), you can control the number of results returned using the resultOptions parameter:

import { SearchOutput } from '@partium/js-sdk';

Partium.search.performSearch(
  {
    organizationName: '<organization-name>',
    searchLanguage: '<search-language-code>',
    text: 'valve',
  },
  undefined, // searchEventContext
  undefined, // projection (uses default)
  {
    limit: 50, // Return up to 50 results (default is 25)
  }
).subscribe((result: SearchOutput) => {
  console.log(`Returned ${result.searchResults.length} results`);
  console.log(`Total available results: ${result.resultsTotalCount}`);

  // Check if more results are available
  const hasMore = result.searchResults.length < result.resultsTotalCount;
  console.log(`More results available: ${hasMore}`);
});

Loading Additional Results

To load additional pages of results from an existing search session, use the getSearchOutput() method with pagination parameters:

import { SearchOutput } from '@partium/js-sdk';

let searchSessionId = null;
let currentResults = [];
const projection = ['results.id', 'results.partiumId', 'results.name', 'results.images'];

// Initial search
Partium.search.performSearch({
  organizationName: '<organization-name>',
  searchLanguage: '<search-language-code>',
  text: 'valve',
}, undefined, undefined, { limit: 25 })
.subscribe((searchOutput: SearchOutput) => {
  searchSessionId = searchOutput.searchInput.searchSessionId;
  currentResults = [...searchOutput.searchResults];

  console.log(`Initial results: ${currentResults.length}`);
  console.log(`Total available: ${searchOutput.resultsTotalCount}`);
});

// Load next page of results
function loadMoreResults() {
  if (!searchSessionId) return;

  Partium.search.getSearchOutput(
    searchSessionId,
    projection,
    {
      skip: currentResults.length, // Skip already loaded results
      limit: 25, // Load next 25 results
    }
  ).subscribe((searchOutput: SearchOutput) => {
    // Append new results to existing ones
    currentResults = [...currentResults, ...searchOutput.searchResults];

    console.log(`Total results now: ${currentResults.length}`);
    console.log(`Total available: ${searchOutput.resultsTotalCount}`);

    // Check if more results are still available
    const hasMore = currentResults.length < searchOutput.resultsTotalCount;
    console.log(`More results available: ${hasMore}`);
  });
}

Page Navigation

In addition to "load more" functionality, you can implement traditional page-based navigation where users can jump directly to specific page numbers (page 2, page 3, etc.).

Using performSearch for Pagination

You can use performSearch() in two ways for pagination:

Independent Page Requests (New Search Sessions)

import { SearchOutput } from '@partium/js-sdk';

const searchInput = {
  organizationName: '<organization-name>',
  searchLanguage: '<search-language-code>',
  text: 'valve',
};

// Fetch Page 1 (first 25 results) - creates new search session
Partium.search.performSearch(
  searchInput,
  undefined,
  undefined,
  { skip: 0, limit: 25 }
).subscribe((searchOutput: SearchOutput) => {
  console.log('Page 1 results:', searchOutput.searchResults);
});

// Fetch Page 2 (results 26-50) - creates another new search session
Partium.search.performSearch(
  searchInput,
  undefined,
  undefined,
  { skip: 25, limit: 25 }
).subscribe((searchOutput: SearchOutput) => {
  console.log('Page 2 results:', searchOutput.searchResults);
});

Continuing Search Sessions

import { SearchOutput } from '@partium/js-sdk';

let searchSessionId = null;

const baseSearchInput = {
  organizationName: '<organization-name>',
  searchLanguage: '<search-language-code>',
  text: 'valve',
};

// Initial search to get the search session
Partium.search.performSearch(baseSearchInput, undefined, undefined, { limit: 25 })
.subscribe((searchOutput: SearchOutput) => {
  searchSessionId = searchOutput.searchInput.searchSessionId;
  console.log('Page 1 results:', searchOutput.searchResults);
});

// Fetch Page 2 using the same search session
Partium.search.performSearch({
  ...baseSearchInput,
  searchSessionId: searchSessionId,
}, undefined, undefined, { skip: 25, limit: 25 })
.subscribe((searchOutput: SearchOutput) => {
  console.log('Page 2 results:', searchOutput.searchResults);
});

// Fetch Page 3 using the same search session
Partium.search.performSearch({
  ...baseSearchInput,
  searchSessionId: searchSessionId,
}, undefined, undefined, { skip: 50, limit: 25 })
.subscribe((searchOutput: SearchOutput) => {
  console.log('Page 3 results:', searchOutput.searchResults);
});

Using getSearchOutput for Pagination

Alternatively, you can use getSearchOutput() to fetch pages from an existing search session:

import { SearchOutput } from '@partium/js-sdk';

let searchSessionId = null;
const projection = ['results.id', 'results.partiumId', 'results.name', 'results.images'];

// Initial search (Page 1)
Partium.search.performSearch({
  organizationName: '<organization-name>',
  searchLanguage: '<search-language-code>',
  text: 'valve',
}, undefined, undefined, { limit: 25 })
.subscribe((searchOutput: SearchOutput) => {
  searchSessionId = searchOutput.searchInput.searchSessionId;
  console.log('Page 1 results:', searchOutput.searchResults);
});

// Fetch Page 2 using getSearchOutput
Partium.search.getSearchOutput(
  searchSessionId,
  projection,
  { skip: 25, limit: 25 }
).subscribe((searchOutput: SearchOutput) => {
  console.log('Page 2 results:', searchOutput.searchResults);
});

// Fetch Page 3 using getSearchOutput
Partium.search.getSearchOutput(
  searchSessionId,
  projection,
  { skip: 50, limit: 25 }
).subscribe((searchOutput: SearchOutput) => {
  console.log('Page 3 results:', searchOutput.searchResults);
});

Custom Page Sizes

You can use different page sizes for different scenarios:

import { SearchOutput } from '@partium/js-sdk';

// Load results 101-150 (page 3 with page size 50)
Partium.search.getSearchOutput(
  searchSessionId,
  ['results.id', 'results.partiumId', 'results.name'],
  {
    skip: 100, // Skip first 100 results
    limit: 50, // Return next 50 results
  }
).subscribe((searchOutput: SearchOutput) => {
  console.log('Page 3 results:', searchOutput.searchResults);
});

API Reference

Result Options Parameters

Both performSearch() and getSearchOutput() methods accept the same pagination parameters in their resultOptions parameter:

Parameter	Type	Description	Default
limit	number	Maximum number of results to return	25
skip	number	Number of results to skip (used for pagination)	0

Calculating Skip Values

To fetch a specific page, calculate the skip value using:

skip = (pageNumber - 1) × pageSize

Examples:

• Page 1: skip = 0, limit = 25
• Page 2: skip = 25, limit = 25
• Page 3: skip = 50, limit = 25

Method Comparison

Method	Approach	Use Case	Pros	Cons
performSearch() without searchSessionId	Independent requests	Static pagination, user jumps to specific pages	• Each request is independent • No session dependency • Can change search parameters	• Creates new search sessions • May affect analytics tracking
performSearch() with searchSessionId	Session continuation	Dynamic pagination within a session	• Full search input flexibility • Can modify search parameters • Maintains session continuity	• Requires managing searchSessionId • Must provide full search input
getSearchOutput()	Session-based	Load more results, sequential pagination	• Minimal parameters required • Better for analytics • Faster subsequent requests	• Requires existing search session • Cannot change search parameters • Sessions can expire

Error Handling

Always implement proper error handling for pagination requests:

import { SearchOutput, SdkError } from '@partium/js-sdk';

function loadMoreResults() {
  Partium.search
    .getSearchOutput(searchSessionId, projection, {
      skip: currentResults.length,
      limit: pageSize,
    })
    .subscribe({
      next: (searchOutput) => {
        currentResults = [...currentResults, ...searchOutput.searchResults];
        updateUI();
      },
      error: (error: SdkError) => {
        if (error.code === 'SEARCH_SESSION_NOT_FOUND') {
          console.log('Search session expired, please start a new search');
          // Redirect to new search
        } else if (error.code === 'TIMEOUT') {
          console.log('Request timed out, please try again');
          // Show retry button
        } else {
          console.error('Failed to load more results:', error);
          // Show generic error message
        }
      },
    });
}

Performance Tip

For optimal performance, avoid loading all results at once. Instead, implement "infinite scroll" or "load more" patterns that fetch results as needed.