API Reference / API Methods / Search / Find Object

Aug. 16, 2022

Find Object

Required API Key: any key with the search ACL

Method signature

$index->findObject(function callback)

$index->findObject(function callback, {
    // All the following parameters are optional
    'query' => string,
    'paginate' => bool
})

index.find_object(block|lambda callback, Hash opts = {
  String query = '',
  bool paginate = true,
  # any requestOptions
})

index.findObject(function callback)

index.findObject(function callback, {
    // All the following parameters are optional
    query: string,
    paginate: bool,
    // + any requestOptions
})

index.find_object(function callback)

index.find_object(function callback, {
    // All the following parameters are optional
    'query' => string,
    'paginate' => bool
})

index.findObject<T: Codable>(
  matching predicate: (T) -> Bool,
  for query: Query = Query(),
  paginate: Bool = true,
  requestOptions: RequestOptions? = nil,
  completion: Result<HitWithPosition<T>?> -> Void
)

suspend fun findObject(
  match: (ResponseSearch.Hit) -> Boolean,
  query: Query = Query(),
  paginate: Boolean = true,
  requestOptions: RequestOptions? = null
): ResponseHitWithPosition?

index.FindObject(
  function callback,
  string query,
  bool paginate
})

index.findObject(
  function callback,
  string query,
  bool paginate
})

index.FindObject(
  function callback,
  string query,
  bool paginate
)

helper.findObject(
  string index
  function callback,
  string query,
  bool paginate
})

See code examples

About this method

We released a new version of the PHP API client in public beta. Read the beta documentation for more information.

We released a new version of the JavaScript API client in public beta. Read the beta documentation for more information.

We released a new version of the Java API client in public beta. Read the beta documentation for more information.

You’re currently reading the JavaScript API client v4 documentation. Check the migration guide to learn how to upgrade from v3 to v4. You can still access the v3 documentation.

You’re currently reading the Ruby API client v2 documentation. Check the migration guide to learn how to upgrade from v1 to v2. You can still access the v1 documentation.

Find an object by the given condition. Can be used to debug relevance.

findObject may be used to debug the relevance of a specific object. This method accepts a condition and returns the first matching object along with its position information in the result set.

The findObject method uses search internally so it can also retrieve the position for a given query. For simply retrieving an object, you can use the more efficient getObjects method instead.

Examples

Read the Algolia CLI documentation for more information.

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
$index->findObject(function($obj) {
  return array_key_exists('firstname', $obj) && 'Jimmie' === $obj['firstname'];
});

// With a query
$options1 = [ 'query' => 'query string' ];
$index->findObject(function($obj) {
  return array_key_exists('firstname', $obj) && 'Jimmie' === $obj['firstname'];
}, $options1);

// With a query and only the first page
$options2 = [ 'query' => 'query string', 'paginate' => false ];
$index->findObject(function($obj) {
  return array_key_exists('firstname', $obj) && 'Jimmie' === $obj['firstname'];
}, $options2);

1
2
3
4
5
6
7
8
9
10
11
12
object = index.find_object(->(obj) { obj.key?('firstname') and obj['firstname'] == 'Jimmie' })

# With a query
object = index.find_object(->(obj) { obj.key?('firstname') and obj['firstname'] == 'Jimmie' }, {
  'query' => 'query string'
})

# With a query and only in the first page
object = index.find_object(->(obj) { obj.key?('firstname') and obj['firstname'] == 'Jimmie' }, {
  'query' => 'query string',
  'paginate' => false
})

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
index.findObject(hit => hit.firstname == "Jimmie")
  .then(obj => {
    console.log(obj);
  });

// With a query
index.findObject(hit => hit.firstname == "Jimmie", {
  query: "query string"
}).then(obj => {
  console.log(obj);
});

// With a query and only in the first page
index.findObject(hit => hit.firstname == "Jimmie", {
  query: "query string",
  paginate: false
}).then(obj => {
  console.log(obj);
});

1
2
3
4
5
6
7
8
9
10
11
12
result = index.find_object(lambda hit: hit.get('firstname') == 'Jimmie')

# With a query
result = index.find_object(lambda hit: hit.get('firstname') == 'Jimmie', {
    'query': 'query string'
})

# With a query and only in the first page
result = index.find_object(lambda hit: hit.get('firstname') == 'Jimmie', {
    'query': 'query string',
    'paginate': False
})

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
let predicate: (JSON) -> Bool = { hit in
  return hit["firstname"] == "Jimmie"
}

index.findObject(matching: predicate) { result in
  if case .success(let response) = result {
    print("Response: \(response)")
  }
}

// With a query
index.findObject(matching: predicate, for: Query("query string")) { result in
  if case .success(let response) = result {
    print("Response: \(response)")
  }
}

// With a query and only in the first page
index.findObject(matching: predicate,
                 for: Query("query string"),
                 paginate: false) { result in
  if case .success(let response) = result {
    print("Response: \(response)")
  }
}

1
2
3
4
5
6
val match: (ResponseSearch.Hit) -> Boolean = {
    it.json.getPrimitive("firstname").content == "Jimmie"
}
index.findObject(match)
index.findObject(match, Query("query string"))
index.findObject(match, Query("query string"), paginate = false)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
index.FindObject<Employee>(
  hit => hit.Firstname.Equals("Jimmie"),
  new Query());

// With a query
index.FindObject<Employee>(
  hit => hit.Firstname.Equals("Jimmie"),
  new Query("query string"));

// With a query and only in the first page
index.FindObject<Employee>(
  hit => hit.Firstname.Equals("Jimmie"),
  new Query("query string"),
  false);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
index.findObject(
    x -> x.getFirstName().equals("Jimmie"),
    new Query(""));

// With a query
index.findObject(
    x -> x.getFirstName().equals("Jimmie"),
    new Query("query string"));

// With a query and only in the first page
index.findObject(
    x -> x.getFirstName().equals("Jimmie"),
    new Query("query string"),
    false);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
f := func(o map[string]interface{}) bool {
    itf, ok := o["firstname"]
    if !ok {
        return false
    }
    firstname, ok := itf.(string)
    return ok && firstname == "Jimmie"
}

index.FindObject(f, "", true)

// With a query
index.FindObject(f, "query string", true)

// With a query and only in the first page
index.FindObject(f, "query string", false)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
helper.findObject(
  indexName,
  Query(),
  (e: Employee) => e.firstName == "jimmie")

// With a query
helper.findObject(
  indexName,
  Query(query = Some("query string")),
  (e: Employee) => e.firstName == "jimmie"))

// With a query and only in the first page
helper.findObject(
  indexName,
  Query(query = Some("query string")),
  (e: Employee) => e.firstName == "jimmie",
  paginate = false)

Parameters

`callback`	type: function Required The callback used to find the object.
`query`	type: string default: empty string Optional The query used to search.
`paginate`	type: boolean default: true Optional Whether to paginate the search results.
`requestOptions`	type: key/value mapping default: No request options Optional A mapping of `requestOptions` to send along with the request. In addition to sending extra HTTP headers or setting timeouts, you can use `requestOptions` to specify search parameters, when using this method.
`index`	type: string Required Only for Scala - The name of the index to query.

Response

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

          {
  "object": {
    "firstname": "Jimmie",
    "lastname": "Barninger",
    "_highlightResult": {
      "firstname": {
        "value": "<em>Jimmie</em>",
        "matchLevel": "partial"
      },
      "lastname": {
        "value": "Barninger",
        "matchLevel": "none"
      },
      "company": {
        "value": "California <em>Paint</em> & Wlpaper Str",
        "matchLevel": "partial"
      }
    }
  },
  "position": 0,
  "page": 0
}

        


          object

key/value mapping

The hit matching your callback.

A hit is made of the schemaless JSON object that you stored in the index.

However, Algolia enriches them with additional fields like _highlightResult.

object: {
    field1 : "",
    field2 : "",
    [...],

    _highlightResult: {
      [...]
    }
}


          position

integer

Number of the matching object’s position in the result set (zero-based).


          page