API Reference / API Methods / Manage indices / Browse index

Jan. 28, 2022

Browse Index

Required API Key: any key with the browse ACL

Method signature

$index->browseObjects()

$index->browseObjects([
  // All the following parameters are optional
  'query' => string,
  // + any browseParameters
  // + any requestOptions
])

index.browse_objects(Hash opts = {
  query: String ,
  # any browseParameters
  # any requestOptions
})

index.browseObjects({
  // A `batch` callback function that's called
  // on every batch of hits with the
  // signature: (hits: THit[]) => any
  batch: function
})

index.browseObjects({
  // A `batch` callback function that's called
  // on every batch of hits with the
  // signature: (hits: THit[]) => any
  batch: function,
  // All the following parameters are optional
  query: string,
  // + any browseParameters
  // + any requestOptions
})

index.browse_objects()
index.browse_objects({
    query: string,
    # + any browseParameters
    # + any requestOptions
})

index.browse(
  query: Query,
  requestOptions: RequestOptions? = nil,
  completion: Result<SearchResponse> -> Void
)

// browseParameters can be set on the Query object

suspend fun Index.browseObjects(
     query: Query = Query(),
     requestOptions: RequestOptions? = null
): List<ResponseSearch>

index.Browse(
  new BrowseIndexQuery(String query)

  // All the following parameters are optional
  requestOptions:  RequestOptions
)
// browseParameters can be set on the BrowseIndexQuery object

index.browseObjects(new BrowseIndexQuery(String query))
index.browseObjects(new BrowseIndexQuery(String query), RequestOptions requestOptions)

// browseParameters can be set on the Query object

index.BrowseObjects(
  opt.Query("query": string),
  // + any browseParameters
)

browse index "myIndex" query Query(query = Some(query))
// browseParameters can be set in the Query object

See code examples

About this method # A

Get all index content without any record limit. Can be used for backups.

The browse method is an alternative to the Search index method. If you need to retrieve the full content of your index (for backup, SEO purposes or for running a script on it), you should use this method instead.

Results are ranked by attributes and custom ranking.

But for performance reasons, there is no ranking based on:

distinct
typo-tolerance
number of matched words
proximity
geo distance

The analytics API doesn’t collect data when using browse.

You shouldn’t use this method for building a search UI. Instead, use search along with the paginationLimitedTo setting to retrieve more than 1,000 results.

If you want to reduce the payload size of the browse response and don’t need all attributes in your records, you can use attributesToRetrieve to declare which attributes to retrieve.

Examples # A

Browse an index (recommended way)#

This example shows how to iterate over the whole index:

Copy

1
2
3
4
5
6
// Empty query will match all records
$iterator = $index->browseObjects(['query' => '', 'filters' => 'i<42']);

foreach ($iterator as $hit) {
  var_dump($hit);
}

1
2
3
4
5
6
7
8
9
let hits = [];

index.browseObjects({
  query: '', // Empty query will match all records
  filters: 'i<42',
  batch: batch => {
    hits = hits.concat(batch);
  }
}).then(() => console.log(hits));

1
2
3
4
5
6
7
var query = Query("") // Empty query will match all records
query.filters = "i<42"
index.browse(query: query) { result in
  if case .success(let response) = result {
    print("Response: \(response)")
  }
}

1
2
3
4
5
6
7
8
IndexIterator<T> indexIterator = index.Browse<T>(new BrowseIndexQuery { Filters = "i<42"});

var hits = new List<T>();

foreach (var hit in indexIterator)
{
    hits.Add(hit);
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
it, err := index.BrowseObjects(
    opt.Query(""),
    opt.Filters("i<42"),
)

// You can either retrieve an empty interface for each object or pass a
// struct object as a parameter of the Next() call, which will try to
// deserialize the object directly.
var interfaceObject interface{}
var structObject struct { ... }

for {
    if interfaceObject, err = it.Next(&structObject); err != nil {
        if err == io.EOF {
            // End of results
        } else {
            // Error while browsing
        }
        break
    }
    fmt.Println(structObject)
}

Retrieve only certain attributes when browsing#

This example shows how to iterate over the whole index and only retrieve certain attributes:

Copy

1
2
3
4
5
6
// Empty query will match all records
$iterator = $index->browseObjects(['query' => '', 'attributesToRetrieve' => [ 'title', 'content' ]]);

foreach ($iterator as $hit) {
  var_dump($hit);
}

1
2
3
4
5
6
7
8
9
10
11
12
let hits = [];

index.browseObjects({
  query: '', // Empty query will match all records
  attributesToRetrieve: [
      "title",
      "content"
    ],
  batch: batch => {
    hits = hits.concat(batch);
  }
}).then(() => console.log(hits));

1
2
3
4
5
6
query = '' # Empty query will match all records

res = index.browse_objects({'query': query, 'attributesToRetrieve': [ 'title', 'content' ]})

for hit in res:
    print(hit)

1
2
3
4
5
6
7
8
9
10
var query = Query("") // Empty query will match all records
query.set(\.attributesToRetrieve, to: [
      "title",
      "content"
    ])
index.browse(query: query) { result in
  if case .success(let response) = result {
    print("Response: \(response)")
  }
}

1
2
3
4
5
6
7
8
IndexIterator<T> indexIterator = index.Browse<T>(new BrowseIndexQuery { AttributesToRetrieve = new List<string> { "title", "content" } });

var hits = new List<T>();

foreach (var hit in indexIterator)
{
    hits.Add(hit);
}

1
2
3
4
5
6
7
8
9
List<T> hits = new ArrayList<>();

for (T hit : index.browseObjects(new BrowseIndexQuery().setAttributesToRetrieve(Arrays.asList(
      "title",
      "content"
    )))
  ) {
  hits.add(hit);
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
it, err := index.BrowseObjects(
    opt.Query(""),
    opt.AttributesToRetrieve(
      "title",
      "content",
    ),
)

// You can either retrieve an empty interface for each object or pass a
// struct object as a parameter of the Next() call, which will try to
// deserialize the object directly.
var interfaceObject interface{}
var structObject struct { ... }

for {
    if interfaceObject, err = it.Next(&structObject); err != nil {
        if err == io.EOF {
            // End of results
        } else {
            // Error while browsing
        }
        break
    }
    fmt.Println(structObject)
}

1
2
3
4
5
val syncHelper = AlgoliaSyncHelper(client)
val q = Query(query = Some("text"), attributesToRetrieve = Some(Seq("title","content")))
syncHelper
  .browse("myIndex", q)
  .map(println)

1
2
3
4
5
6
7
8
9
10
val query = query("") {
attributesToRetrieve {
    +"title"
    +"content"
  }
}

index.browseObjects(query).forEach { responseSearch ->
    println(responseSearch.hits)
}

Browse an index and send extra HTTP headers#

Copy

1
2
3
4
5
6
7
8
9
10
11
$searchParameters = [];

$iterator = $index->browseObjects([
  'query' => '', // Empty query will match all records
  'filters' => 'i<42',
  'X-Forwarded-For' => '94.228.178.246'
]);

foreach ($iterator as $hit) {
  var_dump($hit);
}

1
2
3
4
5
6
7
8
9
10
11
opts = {
  query: '', # Empty query matches all records
  filters: 'i=42',
  headers: {
    'X-Forwarded-For': '94.228.178.246'
  }
}

index.browse_objects(opts) do |hit|
  puts hit
end

1
2
3
4
5
6
7
8
9
10
11
12
let hits = [];

index.browseObjects({
  query: '', // Empty query will match all records
  filters: 'i<42',
  headers: {
    'X-Forwarded-For': '94.228.178.246'
  },
  batch: batch => {
    hits = hits.concat(batch);
  }
}).then(() => console.log(hits));

1
2
3
4
5
6
7
8
9
10
query = '' # Empty query will match all records

res = index.browse_objects({
    'query': query,
    'filters': 'i<42',
    'X-Forwarded-For': '94.228.178.246'
})

for hit in res:
    print(hit)

1
2
3
4
5
6
7
8
9
var requestOptions = RequestOptions()
requestOptions.headers["X-Algolia-User-ID"] = "user123"
var query = Query("") // Empty query will match all records
query.filters = "i<42"
index.browse(query: query, requestOptions: requestOptions) { result in
  if case .success(let response) = result {
    print("Response: \(response)")
  }
}

1
2
3
4
5
6
7
8
9
List<T> hits = new ArrayList<>();

IndexIterable<T> indexIterable = index.browseObjects(
  new BrowseIndexQuery().setFilters("i<42"),
  new RequestOptions().addExtraHeader("X-Algolia-User-ID", "user123"));

for (T hit : indexIterable)  {
  hits.add(hit);
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
it, err := index.BrowseObjects(
    opt.Query(""),
    opt.Filters("i<42"),
    opt.ExtraHeaders(map[string]string{"X-Algolia-User-ID", "userID1"})
)

// You can either retrieve an empty interface for each object or pass a
// struct object as a parameter of the Next() call, which will try to
// deserialize the object directly.
var interfaceObject interface{}
var structObject struct { ... }

for {
    if interfaceObject, err = it.Next(&structObject); err != nil {
        if err == io.EOF {
            // End of results
        } else {
            // Error while browsing
        }
        break
    }
    fmt.Println(structObject)
}

1
2
3
4
5
6
7
val syncHelper = AlgoliaSyncHelper(client)
val q = Query(query = Some("text"), filters = Some("i<42"))
syncHelper
  .browse("myIndex", q, RequestOptions(
    extraHeaders = Some(Map("X-Algolia-User-ID" => "user123"))
  )
  .map(println)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
val query = Query(query = "")
val requestOptions = requestOptions {
    header("X-Algolia-User-ID", "user123")
}

index.browseObjects(query, requestOptions).forEach { responseSearch ->
    println(responseSearch.hits)
}

csharp: |

var requestOptions = new RequestOptions
{
    Headers = new Dictionary<string,string>{ { "X-Algolia-User-ID", "userID1" } }
};

IndexIterator<T> indexIterator = index.BrowseFrom<T>(new BrowseIndexQuery { Filters = "i<42" }, requestOptions);

foreach (var hit in indexIterator)
{
    Console.WriteLine(hit.ToString());
}

Parameters # A


            query

type: string

Required

Query to search. Accepts every character and every character entered will be used in the search.

Empty query can be used to fetch all records.


            browseParameters

type: key/value mapping

default: No browse parameters

Optional

Browse compatible search parameters.

Can contain any of the search parameters. Some useful ones for browse include:

for retrieving only certain attributes and decreasing payload size
- attributesToRetrieve
for filtering:
for pagination:

There are certain search parameters the engine overrides:

typoTolerance can only be true or false; if you settypoTolerance to min or strict, we set it to true—records matching up to 2 typos will be retrieved
the engine forces distinct to false
the engine forces enableRules to false
the engine forces ignorePlurals to false
the engine forces advancedSyntax to false
the engine forces facets to []
the engine forces getRankingInfo to false
the engine forces attributesToHighlight to []
the engine forces attributesToSnippet to []
the engine forces optionalFilters to []


            requestOptions

type: key/value mapping

default: No request options

Optional

A mapping of requestOptions to send along with the query.

Response # A

This section shows the JSON response returned by the API. Since each language encapsulates this response inside objects specific to that language and/or implementation, the actual type in your language might differ from what’s written here. You can view the response in the logs (using the getLogs method).

JSON format#

Copy

          {
  "hits": [
    {
      "firstname": "Jimmie",
      "lastname": "Barninger",
      "objectID": "433"
    }
  ],
  "processingTimeMS": 7,
  "query": "",
  "params": "filters=level%3D20",
  "cursor": "ARJmaWx0ZXJzPWxldmVsJTNEMjABARoGODA4OTIzvwgAgICAgICAgICAAQ=="
}

        

`hits` #	list Retrieved records.
`cursor` #	string A cursor to retrieve the next chunk of data. Used with `browseFrom`. If absent, it means that the end of the index has been reached.
`params` #	string URL-encoded search parameters used to filter the results.
`query` #	string Query text used to filter the results.
`processingTimeMS` #	integer Time that the server took to process the request, in milliseconds. This does not include network time.
`nbHits` #	integer Number of objects in the index. Present only when the query is empty and the browse is not filtered.
`page` #	integer Index of the current page (zero-based). Present only when the query is empty and the browse is not filtered.
`hitsPerPage` #	integer The maximum number of hits returned per page. Present only when the query is empty and the browse is not filtered.
`nbPages` #	integer The number of returned pages. Calculation is based on total number of hits (nbHits) divided by the number of hits per page (hitsPerPage), rounded to the nearest highest integer. Present only when the query is empty and the browse is not filtered.

Did you find this page helpful?

Browse Index

About this method # Found an issue? Edit this page A Edit this page

Examples # Found an issue? Edit this page A Edit this page

Browse an index (recommended way)#

Retrieve only certain attributes when browsing#

Browse an index and send extra HTTP headers#

Parameters # Found an issue? Edit this page A Edit this page

Response # Found an issue? Edit this page A Edit this page

JSON format#

On this page

About this method # A

Examples # A

Parameters # A

Response # A