0
# Search Operations
1
2
Core search functionality providing comprehensive index management, object operations, search queries, rules, synonyms, API key management, and advanced features like user ID mapping and dictionary management. This is the primary interface for most Algolia operations.
3
4
## Capabilities
5
6
### Client Initialization
7
8
Create search clients for both async and sync operations.
9
10
```python { .api }
11
class SearchClient:
12
def __init__(
13
self,
14
app_id: Optional[str] = None,
15
api_key: Optional[str] = None,
16
transporter: Optional[Transporter] = None,
17
config: Optional[SearchConfig] = None
18
) -> None: ...
19
20
@classmethod
21
def create_with_config(
22
cls,
23
config: SearchConfig,
24
transporter: Optional[Transporter] = None
25
) -> SearchClient: ...
26
27
async def close(self) -> None: ...
28
async def set_client_api_key(self, api_key: str) -> None: ...
29
30
class SearchClientSync:
31
def __init__(
32
self,
33
app_id: Optional[str] = None,
34
api_key: Optional[str] = None,
35
transporter: Optional[TransporterSync] = None,
36
config: Optional[SearchConfig] = None
37
) -> None: ...
38
```
39
40
### Search Operations
41
42
Execute search queries across indices with full-text search, filtering, faceting, and ranking options.
43
44
```python { .api }
45
async def search(
46
self,
47
search_method_params: Union[SearchMethodParams, dict]
48
) -> SearchResponse:
49
"""
50
Execute search queries across one or more indices.
51
52
Parameters:
53
- search_method_params: Search configuration with requests array
54
55
Returns:
56
SearchResponse with results for each request
57
"""
58
59
async def browse(
60
self,
61
index_name: str,
62
browse_params: Optional[Union[BrowseParams, dict]] = None,
63
request_options: Optional[Union[dict, RequestOptions]] = None
64
) -> BrowseResponse:
65
"""
66
Browse all objects in an index without search query limitations.
67
68
Parameters:
69
- index_name: Target index name
70
- browse_params: Browse configuration options
71
- request_options: Additional request options
72
73
Returns:
74
BrowseResponse with object data and cursor for pagination
75
"""
76
77
async def browse_objects(
78
self,
79
index_name: str,
80
aggregator: Callable[[BrowseResponse], None],
81
browse_params: Optional[BrowseParamsObject] = None,
82
request_options: Optional[Union[dict, RequestOptions]] = None
83
) -> BrowseResponse:
84
"""
85
Browse all objects in an index with automatic pagination handling.
86
87
Parameters:
88
- index_name: Target index name
89
- aggregator: Function to process each page of results
90
- browse_params: Browse configuration options
91
- request_options: Additional request options
92
93
Returns:
94
BrowseResponse with final page data
95
"""
96
97
async def search_single_index(
98
self,
99
index_name: str,
100
search_params: Optional[Union[SearchParams, dict]] = None,
101
request_options: Optional[Union[dict, RequestOptions]] = None
102
) -> SearchResponse:
103
"""
104
Search within a single index.
105
106
Parameters:
107
- index_name: Target index name
108
- search_params: Search configuration
109
- request_options: Additional request options
110
111
Returns:
112
SearchResponse with search results
113
"""
114
115
async def search_for_facet_values(
116
self,
117
index_name: str,
118
facet_name: str,
119
search_for_facet_values_request: Optional[Union[SearchForFacetValuesRequest, dict]] = None,
120
request_options: Optional[Union[dict, RequestOptions]] = None
121
) -> SearchForFacetValuesResponse:
122
"""
123
Search for values within a specific facet attribute.
124
125
Parameters:
126
- index_name: Target index name
127
- facet_name: Name of facet attribute to search
128
- search_for_facet_values_request: Search parameters
129
- request_options: Additional request options
130
131
Returns:
132
SearchForFacetValuesResponse with matching facet values
133
"""
134
```
135
136
### Object Management
137
138
Create, read, update, and delete operations for index objects.
139
140
```python { .api }
141
async def save_object(
142
self,
143
index_name: str,
144
body: Union[dict, Any],
145
request_options: Optional[Union[dict, RequestOptions]] = None
146
) -> SaveObjectResponse:
147
"""
148
Save a single object to an index.
149
150
Parameters:
151
- index_name: Target index name
152
- body: Object data with objectID
153
- request_options: Additional request options
154
155
Returns:
156
SaveObjectResponse with task information
157
"""
158
159
async def save_objects(
160
self,
161
index_name: str,
162
objects: List[Union[dict, Any]],
163
wait_for_tasks: bool = False,
164
batch_size: int = 1000,
165
request_options: Optional[Union[dict, RequestOptions]] = None
166
) -> List[BatchResponse]:
167
"""
168
Save multiple objects to an index with automatic chunking.
169
170
Parameters:
171
- index_name: Target index name
172
- objects: List of objects to save
173
- wait_for_tasks: Wait for all tasks to complete
174
- batch_size: Objects per batch
175
- request_options: Additional request options
176
177
Returns:
178
List of BatchResponse objects for each chunk
179
"""
180
181
182
async def get_objects(
183
self,
184
get_objects_params: Union[GetObjectsParams, dict],
185
request_options: Optional[Union[dict, RequestOptions]] = None
186
) -> GetObjectsResponse:
187
"""
188
Retrieve multiple objects by their objectIDs.
189
190
Parameters:
191
- get_objects_params: Parameters with requests array
192
- request_options: Additional request options
193
194
Returns:
195
GetObjectsResponse with retrieved objects
196
"""
197
198
async def get_object(
199
self,
200
index_name: str,
201
object_id: str,
202
attributes_to_retrieve: Optional[List[str]] = None,
203
request_options: Optional[Union[dict, RequestOptions]] = None
204
) -> dict:
205
"""
206
Retrieve a single object by its objectID with optional attribute filtering.
207
208
Parameters:
209
- index_name: Target index name
210
- object_id: Unique object identifier
211
- attributes_to_retrieve: Specific attributes to retrieve
212
- request_options: Additional request options
213
214
Returns:
215
Object data as dictionary
216
"""
217
218
async def delete_object(
219
self,
220
index_name: str,
221
object_id: str,
222
request_options: Optional[Union[dict, RequestOptions]] = None
223
) -> DeletedAtResponse:
224
"""
225
Delete a single object from an index.
226
227
Parameters:
228
- index_name: Target index name
229
- object_id: Unique object identifier
230
- request_options: Additional request options
231
232
Returns:
233
DeletedAtResponse with task information
234
"""
235
236
async def delete_objects(
237
self,
238
index_name: str,
239
object_ids: List[str],
240
wait_for_tasks: bool = False,
241
batch_size: int = 1000,
242
request_options: Optional[Union[dict, RequestOptions]] = None
243
) -> List[BatchResponse]:
244
"""
245
Delete multiple objects from an index with automatic chunking.
246
247
Parameters:
248
- index_name: Target index name
249
- object_ids: List of object identifiers to delete
250
- wait_for_tasks: Wait for all tasks to complete
251
- batch_size: Objects per batch
252
- request_options: Additional request options
253
254
Returns:
255
List of BatchResponse objects for each chunk
256
"""
257
258
async def delete_by(
259
self,
260
index_name: str,
261
delete_by_params: Union[DeleteByParams, dict],
262
request_options: Optional[Union[dict, RequestOptions]] = None
263
) -> UpdatedAtResponse:
264
"""
265
Delete objects matching specific filters.
266
267
Parameters:
268
- index_name: Target index name
269
- delete_by_params: Deletion criteria and filters
270
- request_options: Additional request options
271
272
Returns:
273
UpdatedAtResponse with task information
274
"""
275
276
async def partial_update_object(
277
self,
278
index_name: str,
279
object_id: str,
280
attribute_to_update: Union[AttributeToUpdate, dict],
281
create_if_not_exists: Optional[bool] = None,
282
request_options: Optional[Union[dict, RequestOptions]] = None
283
) -> UpdatedAtWithObjectIdResponse:
284
"""
285
Partially update an object's attributes.
286
287
Parameters:
288
- index_name: Target index name
289
- object_id: Unique object identifier
290
- attribute_to_update: Attributes to update
291
- create_if_not_exists: Create object if it doesn't exist
292
- request_options: Additional request options
293
294
Returns:
295
UpdatedAtWithObjectIdResponse with task information
296
"""
297
298
async def partial_update_objects(
299
self,
300
index_name: str,
301
objects: List[Union[dict, Any]],
302
create_if_not_exists: Optional[bool] = None,
303
wait_for_tasks: bool = False,
304
batch_size: int = 1000,
305
request_options: Optional[Union[dict, RequestOptions]] = None
306
) -> List[BatchResponse]:
307
"""
308
Partially update multiple objects' attributes.
309
310
Parameters:
311
- index_name: Target index name
312
- objects: List of objects with updates
313
- create_if_not_exists: Create objects if they don't exist
314
- wait_for_tasks: Wait for all tasks to complete
315
- batch_size: Objects per batch
316
- request_options: Additional request options
317
318
Returns:
319
List of BatchResponse objects for each chunk
320
"""
321
322
async def add_or_update_object(
323
self,
324
index_name: str,
325
object_id: str,
326
body: Dict[str, Any],
327
request_options: Optional[Union[dict, RequestOptions]] = None
328
) -> UpdatedAtWithObjectIdResponse:
329
"""
330
Add or update an object with a specific objectID.
331
332
Parameters:
333
- index_name: Target index name
334
- object_id: Unique object identifier
335
- body: Object data
336
- request_options: Additional request options
337
338
Returns:
339
UpdatedAtWithObjectIdResponse with task information
340
"""
341
342
async def save_objects_with_transformation(
343
self,
344
index_name: str,
345
objects: List[Dict[str, Any]],
346
wait_for_tasks: bool = False,
347
batch_size: int = 1000,
348
request_options: Optional[Union[dict, RequestOptions]] = None
349
) -> List[IngestionWatchResponse]:
350
"""
351
Save objects with data transformation applied.
352
353
Parameters:
354
- index_name: Target index name
355
- objects: Objects to save with transformation
356
- wait_for_tasks: Wait for all tasks to complete
357
- batch_size: Objects per batch
358
- request_options: Additional request options
359
360
Returns:
361
List of IngestionWatchResponse objects
362
"""
363
```
364
365
### Index Management
366
367
Manage indices including creation, deletion, copying, and settings configuration.
368
369
```python { .api }
370
async def list_indices(
371
self,
372
page: Optional[int] = None,
373
hits_per_page: Optional[int] = None,
374
request_options: Optional[Union[dict, RequestOptions]] = None
375
) -> ListIndicesResponse:
376
"""
377
List all indices in the application.
378
379
Parameters:
380
- page: Page number for pagination
381
- hits_per_page: Number of indices per page
382
- request_options: Additional request options
383
384
Returns:
385
ListIndicesResponse with index information
386
"""
387
388
async def delete_index(
389
self,
390
index_name: str,
391
request_options: Optional[Union[dict, RequestOptions]] = None
392
) -> DeletedAtResponse:
393
"""
394
Delete an index and all its data.
395
396
Parameters:
397
- index_name: Index name to delete
398
- request_options: Additional request options
399
400
Returns:
401
DeletedAtResponse with task information
402
"""
403
404
async def operation_index(
405
self,
406
index_name: str,
407
operation_index_params: Union[OperationIndexParams, dict],
408
request_options: Optional[Union[dict, RequestOptions]] = None
409
) -> UpdatedAtResponse:
410
"""
411
Perform index operations (copy, move).
412
413
Parameters:
414
- index_name: Source index name
415
- operation_index_params: Operation parameters
416
- request_options: Additional request options
417
418
Returns:
419
UpdatedAtResponse with task information
420
"""
421
422
423
async def clear_objects(
424
self,
425
index_name: str,
426
request_options: Optional[Union[dict, RequestOptions]] = None
427
) -> UpdatedAtResponse:
428
"""
429
Clear all objects from an index while preserving settings and rules.
430
431
Parameters:
432
- index_name: Target index name
433
- request_options: Additional request options
434
435
Returns:
436
UpdatedAtResponse with task information
437
"""
438
439
def index_exists(self, index_name: str) -> bool:
440
"""
441
Check if an index exists.
442
443
Parameters:
444
- index_name: Index name to check
445
446
Returns:
447
True if index exists, False otherwise
448
"""
449
```
450
451
### Settings and Configuration
452
453
Manage index settings including searchable attributes, ranking, facets, and other configuration options.
454
455
```python { .api }
456
async def get_settings(
457
self,
458
index_name: str,
459
request_options: Optional[Union[dict, RequestOptions]] = None
460
) -> SettingsResponse:
461
"""
462
Get current index settings.
463
464
Parameters:
465
- index_name: Target index name
466
- request_options: Additional request options
467
468
Returns:
469
SettingsResponse with current settings
470
"""
471
472
async def set_settings(
473
self,
474
index_name: str,
475
index_settings: Union[IndexSettings, dict],
476
forward_to_replicas: Optional[bool] = None,
477
request_options: Optional[Union[dict, RequestOptions]] = None
478
) -> UpdatedAtResponse:
479
"""
480
Update index settings.
481
482
Parameters:
483
- index_name: Target index name
484
- index_settings: New settings configuration
485
- forward_to_replicas: Apply to replica indices
486
- request_options: Additional request options
487
488
Returns:
489
UpdatedAtResponse with task information
490
"""
491
```
492
493
### Rules Management
494
495
Manage search rules for query processing, result ranking, and merchandising.
496
497
```python { .api }
498
async def search_rules(
499
self,
500
index_name: str,
501
search_rules_params: Optional[Union[SearchRulesParams, dict]] = None,
502
request_options: Optional[Union[dict, RequestOptions]] = None
503
) -> SearchRulesResponse:
504
"""
505
Search for rules in an index.
506
507
Parameters:
508
- index_name: Target index name
509
- search_rules_params: Search parameters
510
- request_options: Additional request options
511
512
Returns:
513
SearchRulesResponse with matching rules
514
"""
515
516
async def get_rule(
517
self,
518
index_name: str,
519
object_id: str,
520
request_options: Optional[Union[dict, RequestOptions]] = None
521
) -> Rule:
522
"""
523
Get a specific rule by its objectID.
524
525
Parameters:
526
- index_name: Target index name
527
- object_id: Rule identifier
528
- request_options: Additional request options
529
530
Returns:
531
Rule object
532
"""
533
534
async def save_rule(
535
self,
536
index_name: str,
537
object_id: str,
538
rule: Union[Rule, dict],
539
forward_to_replicas: Optional[bool] = None,
540
request_options: Optional[Union[dict, RequestOptions]] = None
541
) -> UpdatedAtResponse:
542
"""
543
Save a rule to an index.
544
545
Parameters:
546
- index_name: Target index name
547
- object_id: Rule identifier
548
- rule: Rule configuration
549
- forward_to_replicas: Apply to replica indices
550
- request_options: Additional request options
551
552
Returns:
553
UpdatedAtResponse with task information
554
"""
555
556
async def save_rules(
557
self,
558
index_name: str,
559
rules: Union[List[Rule], list[dict]],
560
forward_to_replicas: Optional[bool] = None,
561
clear_existing_rules: Optional[bool] = None,
562
request_options: Optional[Union[dict, RequestOptions]] = None
563
) -> UpdatedAtResponse:
564
"""
565
Save multiple rules to an index.
566
567
Parameters:
568
- index_name: Target index name
569
- rules: List of rules to save
570
- forward_to_replicas: Apply to replica indices
571
- clear_existing_rules: Clear existing rules before saving
572
- request_options: Additional request options
573
574
Returns:
575
UpdatedAtResponse with task information
576
"""
577
578
async def delete_rule(
579
self,
580
index_name: str,
581
object_id: str,
582
forward_to_replicas: Optional[bool] = None,
583
request_options: Optional[Union[dict, RequestOptions]] = None
584
) -> UpdatedAtResponse:
585
"""
586
Delete a specific rule from an index.
587
588
Parameters:
589
- index_name: Target index name
590
- object_id: Rule identifier to delete
591
- forward_to_replicas: Apply to replica indices
592
- request_options: Additional request options
593
594
Returns:
595
UpdatedAtResponse with task information
596
"""
597
598
async def clear_rules(
599
self,
600
index_name: str,
601
forward_to_replicas: Optional[bool] = None,
602
request_options: Optional[Union[dict, RequestOptions]] = None
603
) -> UpdatedAtResponse:
604
"""
605
Clear all rules from an index.
606
607
Parameters:
608
- index_name: Target index name
609
- forward_to_replicas: Apply to replica indices
610
- request_options: Additional request options
611
612
Returns:
613
UpdatedAtResponse with task information
614
"""
615
616
async def browse_rules(
617
self,
618
index_name: str,
619
aggregator: Callable[[SearchRulesResponse], None],
620
search_rules_params: Optional[SearchRulesParams] = None,
621
request_options: Optional[Union[dict, RequestOptions]] = None
622
) -> SearchRulesResponse:
623
"""
624
Browse all rules in an index with pagination.
625
626
Parameters:
627
- index_name: Target index name
628
- aggregator: Function to process each page of results
629
- search_rules_params: Search parameters
630
- request_options: Additional request options
631
632
Returns:
633
SearchRulesResponse with rules
634
"""
635
```
636
637
### API Key Management
638
639
Manage API keys for authentication and access control.
640
641
```python { .api }
642
async def add_api_key(
643
self,
644
api_key: Union[ApiKey, dict],
645
request_options: Optional[Union[dict, RequestOptions]] = None
646
) -> AddApiKeyResponse:
647
"""
648
Create a new API key.
649
650
Parameters:
651
- api_key: API key configuration
652
- request_options: Additional request options
653
654
Returns:
655
AddApiKeyResponse with key information
656
"""
657
658
async def get_api_key(
659
self,
660
key: str,
661
request_options: Optional[Union[dict, RequestOptions]] = None
662
) -> GetApiKeyResponse:
663
"""
664
Get API key details.
665
666
Parameters:
667
- key: API key value
668
- request_options: Additional request options
669
670
Returns:
671
GetApiKeyResponse with key details
672
"""
673
674
async def list_api_keys(
675
self,
676
request_options: Optional[Union[dict, RequestOptions]] = None
677
) -> ListApiKeysResponse:
678
"""
679
List all API keys for the application.
680
681
Returns:
682
ListApiKeysResponse with all keys
683
"""
684
685
async def update_api_key(
686
self,
687
key: str,
688
api_key: Union[ApiKey, dict],
689
request_options: Optional[Union[dict, RequestOptions]] = None
690
) -> UpdateApiKeyResponse:
691
"""
692
Update an existing API key.
693
694
Parameters:
695
- key: API key value to update
696
- api_key: Updated key configuration
697
- request_options: Additional request options
698
699
Returns:
700
UpdateApiKeyResponse with update confirmation
701
"""
702
703
async def delete_api_key(
704
self,
705
key: str,
706
request_options: Optional[Union[dict, RequestOptions]] = None
707
) -> DeleteApiKeyResponse:
708
"""
709
Delete an API key.
710
711
Parameters:
712
- key: API key value to delete
713
- request_options: Additional request options
714
715
Returns:
716
DeleteApiKeyResponse with deletion confirmation
717
"""
718
719
async def generate_secured_api_key(
720
self,
721
parent_api_key: str,
722
restrictions: Union[SecuredApiKeyRestrictions, dict]
723
) -> str:
724
"""
725
Generate a secured API key with restrictions.
726
727
Parameters:
728
- parent_api_key: Base API key
729
- restrictions: Security restrictions to apply
730
731
Returns:
732
Secured API key string
733
"""
734
735
async def restore_api_key(
736
self,
737
key: str,
738
request_options: Optional[Union[dict, RequestOptions]] = None
739
) -> AddApiKeyResponse:
740
"""
741
Restore a deleted API key.
742
743
Parameters:
744
- key: API key value to restore
745
- request_options: Additional request options
746
747
Returns:
748
AddApiKeyResponse with restoration confirmation
749
"""
750
751
async def wait_for_api_key(
752
self,
753
key: str,
754
operation: str,
755
api_key: Optional[Union[ApiKey, dict]] = None,
756
max_retries: int = 50,
757
timeout: RetryTimeout = RetryTimeout(),
758
request_options: Optional[Union[dict, RequestOptions]] = None
759
) -> GetApiKeyResponse:
760
"""
761
Wait for an API key operation to be processed.
762
763
Parameters:
764
- key: API key value
765
- operation: Operation type ("add", "update", "delete")
766
- api_key: API key configuration for validation
767
- max_retries: Maximum retry attempts
768
- timeout: Timeout configuration
769
- request_options: Additional request options
770
771
Returns:
772
GetApiKeyResponse when operation completes
773
"""
774
775
def get_secured_api_key_remaining_validity(self, secured_api_key: str) -> int:
776
"""
777
Get remaining validity time for a secured API key.
778
779
Parameters:
780
- secured_api_key: Secured API key to check
781
782
Returns:
783
Remaining validity time in seconds
784
"""
785
```
786
787
### Task Management
788
789
Monitor and wait for asynchronous operations to complete.
790
791
```python { .api }
792
async def wait_for_task(
793
self,
794
index_name: str,
795
task_id: int,
796
max_retries: int = 50,
797
timeout: RetryTimeout = RetryTimeout()
798
) -> GetTaskResponse:
799
"""
800
Wait for an indexing task to complete.
801
802
Parameters:
803
- index_name: Target index name
804
- task_id: Task identifier to wait for
805
- max_retries: Maximum retry attempts
806
- timeout: Timeout configuration
807
808
Returns:
809
GetTaskResponse when task completes
810
"""
811
812
async def get_task(
813
self,
814
index_name: str,
815
task_id: int,
816
request_options: Optional[Union[dict, RequestOptions]] = None
817
) -> GetTaskResponse:
818
"""
819
Get the status of a specific task.
820
821
Parameters:
822
- index_name: Target index name
823
- task_id: Task identifier
824
- request_options: Additional request options
825
826
Returns:
827
GetTaskResponse with current task status
828
"""
829
830
async def get_app_task(
831
self,
832
task_id: int,
833
request_options: Optional[Union[dict, RequestOptions]] = None
834
) -> GetTaskResponse:
835
"""
836
Get the status of an application-level task.
837
838
Parameters:
839
- task_id: Task identifier
840
- request_options: Additional request options
841
842
Returns:
843
GetTaskResponse with current task status
844
"""
845
846
async def wait_for_app_task(
847
self,
848
task_id: int,
849
timeout: RetryTimeout = RetryTimeout(),
850
max_retries: int = 50,
851
request_options: Optional[Union[dict, RequestOptions]] = None
852
) -> GetTaskResponse:
853
"""
854
Wait for an application-level task to complete.
855
856
Parameters:
857
- task_id: Task identifier to wait for
858
- timeout: Timeout configuration
859
- max_retries: Maximum retry attempts
860
- request_options: Additional request options
861
862
Returns:
863
GetTaskResponse when task completes
864
"""
865
```
866
867
### Synonyms Management
868
869
Manage synonyms to improve search relevance by treating different terms as equivalent.
870
871
```python { .api }
872
async def get_synonym(
873
self,
874
index_name: str,
875
object_id: str,
876
request_options: Optional[Union[dict, RequestOptions]] = None
877
) -> SynonymHit:
878
"""
879
Get a specific synonym by its objectID.
880
881
Parameters:
882
- index_name: Target index name
883
- object_id: Synonym identifier
884
- request_options: Additional request options
885
886
Returns:
887
SynonymHit object
888
"""
889
890
async def save_synonym(
891
self,
892
index_name: str,
893
object_id: str,
894
synonym_hit: Union[SynonymHit, dict],
895
forward_to_replicas: Optional[bool] = None,
896
request_options: Optional[Union[dict, RequestOptions]] = None
897
) -> SaveSynonymResponse:
898
"""
899
Save a synonym to an index.
900
901
Parameters:
902
- index_name: Target index name
903
- object_id: Synonym identifier
904
- synonym_hit: Synonym configuration
905
- forward_to_replicas: Apply to replica indices
906
- request_options: Additional request options
907
908
Returns:
909
SaveSynonymResponse with task information
910
"""
911
912
async def save_synonyms(
913
self,
914
index_name: str,
915
synonym_hit: Union[List[SynonymHit], list[dict]],
916
forward_to_replicas: Optional[bool] = None,
917
replace_existing_synonyms: Optional[bool] = None,
918
request_options: Optional[Union[dict, RequestOptions]] = None
919
) -> UpdatedAtResponse:
920
"""
921
Save multiple synonyms to an index.
922
923
Parameters:
924
- index_name: Target index name
925
- synonym_hit: List of synonyms to save
926
- forward_to_replicas: Apply to replica indices
927
- replace_existing_synonyms: Replace all existing synonyms
928
- request_options: Additional request options
929
930
Returns:
931
UpdatedAtResponse with task information
932
"""
933
934
async def search_synonyms(
935
self,
936
index_name: str,
937
search_synonyms_params: Optional[Union[SearchSynonymsParams, dict]] = None,
938
request_options: Optional[Union[dict, RequestOptions]] = None
939
) -> SearchSynonymsResponse:
940
"""
941
Search for synonyms in an index.
942
943
Parameters:
944
- index_name: Target index name
945
- search_synonyms_params: Search parameters
946
- request_options: Additional request options
947
948
Returns:
949
SearchSynonymsResponse with matching synonyms
950
"""
951
952
async def browse_synonyms(
953
self,
954
index_name: str,
955
aggregator: Callable[[SearchSynonymsResponse], None],
956
search_synonyms_params: Optional[SearchSynonymsParams] = None,
957
request_options: Optional[Union[dict, RequestOptions]] = None
958
) -> SearchSynonymsResponse:
959
"""
960
Browse all synonyms in an index with pagination.
961
962
Parameters:
963
- index_name: Target index name
964
- aggregator: Function to process each page of results
965
- search_synonyms_params: Search parameters
966
- request_options: Additional request options
967
968
Returns:
969
SearchSynonymsResponse with synonyms
970
"""
971
972
async def delete_synonym(
973
self,
974
index_name: str,
975
object_id: str,
976
forward_to_replicas: Optional[bool] = None,
977
request_options: Optional[Union[dict, RequestOptions]] = None
978
) -> DeletedAtResponse:
979
"""
980
Delete a specific synonym from an index.
981
982
Parameters:
983
- index_name: Target index name
984
- object_id: Synonym identifier to delete
985
- forward_to_replicas: Apply to replica indices
986
- request_options: Additional request options
987
988
Returns:
989
DeletedAtResponse with task information
990
"""
991
992
async def clear_synonyms(
993
self,
994
index_name: str,
995
forward_to_replicas: Optional[bool] = None,
996
request_options: Optional[Union[dict, RequestOptions]] = None
997
) -> UpdatedAtResponse:
998
"""
999
Clear all synonyms from an index.
1000
1001
Parameters:
1002
- index_name: Target index name
1003
- forward_to_replicas: Apply to replica indices
1004
- request_options: Additional request options
1005
1006
Returns:
1007
UpdatedAtResponse with task information
1008
"""
1009
```
1010
1011
### Batch Operations
1012
1013
Perform bulk operations efficiently with batching and chunking support.
1014
1015
```python { .api }
1016
async def batch(
1017
self,
1018
index_name: str,
1019
batch_write_params: Union[BatchWriteParams, dict],
1020
request_options: Optional[Union[dict, RequestOptions]] = None
1021
) -> BatchResponse:
1022
"""
1023
Perform batch write operations on an index.
1024
1025
Parameters:
1026
- index_name: Target index name
1027
- batch_write_params: Batch operations to perform
1028
- request_options: Additional request options
1029
1030
Returns:
1031
BatchResponse with task information
1032
"""
1033
1034
async def multiple_batch(
1035
self,
1036
batch_params: Union[BatchParams, dict],
1037
request_options: Optional[Union[dict, RequestOptions]] = None
1038
) -> MultipleBatchResponse:
1039
"""
1040
Perform batch operations across multiple indices.
1041
1042
Parameters:
1043
- batch_params: Multi-index batch operations
1044
- request_options: Additional request options
1045
1046
Returns:
1047
MultipleBatchResponse with task information
1048
"""
1049
1050
async def chunked_batch(
1051
self,
1052
index_name: str,
1053
objects: List[Dict[str, Any]],
1054
action: Action = Action.ADDOBJECT,
1055
wait_for_tasks: bool = False,
1056
batch_size: int = 1000,
1057
request_options: Optional[Union[dict, RequestOptions]] = None
1058
) -> List[BatchResponse]:
1059
"""
1060
Perform chunked batch operations for large datasets.
1061
1062
Parameters:
1063
- index_name: Target index name
1064
- objects: Objects to process
1065
- action: Batch action to perform
1066
- wait_for_tasks: Wait for all tasks to complete
1067
- batch_size: Objects per batch
1068
- request_options: Additional request options
1069
1070
Returns:
1071
List of BatchResponse objects for each chunk
1072
"""
1073
1074
async def replace_all_objects(
1075
self,
1076
index_name: str,
1077
objects: List[Dict[str, Any]],
1078
batch_size: int = 1000,
1079
scopes: List[str] = ["settings", "rules", "synonyms"],
1080
request_options: Optional[Union[dict, RequestOptions]] = None
1081
) -> ReplaceAllObjectsResponse:
1082
"""
1083
Replace all objects in an index atomically.
1084
1085
Parameters:
1086
- index_name: Target index name
1087
- objects: New objects to replace with
1088
- batch_size: Objects per batch
1089
- scopes: Index components to preserve
1090
- request_options: Additional request options
1091
1092
Returns:
1093
ReplaceAllObjectsResponse with operation details
1094
"""
1095
```
1096
1097
### User ID Management
1098
1099
Manage user ID mappings for personalization and analytics.
1100
1101
```python { .api }
1102
async def assign_user_id(
1103
self,
1104
x_algolia_user_id: str,
1105
assign_user_id_params: Union[AssignUserIdParams, dict],
1106
request_options: Optional[Union[dict, RequestOptions]] = None
1107
) -> CreatedAtResponse:
1108
"""
1109
Assign a user ID to a cluster.
1110
1111
Parameters:
1112
- x_algolia_user_id: User identifier
1113
- assign_user_id_params: Assignment parameters
1114
- request_options: Additional request options
1115
1116
Returns:
1117
CreatedAtResponse with assignment confirmation
1118
"""
1119
1120
async def get_user_id(
1121
self,
1122
user_id: str,
1123
request_options: Optional[Union[dict, RequestOptions]] = None
1124
) -> UserId:
1125
"""
1126
Get user ID details and cluster assignment.
1127
1128
Parameters:
1129
- user_id: User identifier to lookup
1130
- request_options: Additional request options
1131
1132
Returns:
1133
UserId object with user details
1134
"""
1135
1136
async def list_user_ids(
1137
self,
1138
page: Optional[int] = None,
1139
hits_per_page: Optional[int] = None,
1140
request_options: Optional[Union[dict, RequestOptions]] = None
1141
) -> ListUserIdsResponse:
1142
"""
1143
List all user IDs in the application.
1144
1145
Parameters:
1146
- page: Page number for pagination
1147
- hits_per_page: Number of results per page
1148
- request_options: Additional request options
1149
1150
Returns:
1151
ListUserIdsResponse with user ID list
1152
"""
1153
1154
async def remove_user_id(
1155
self,
1156
user_id: str,
1157
request_options: Optional[Union[dict, RequestOptions]] = None
1158
) -> RemoveUserIdResponse:
1159
"""
1160
Remove a user ID from the cluster.
1161
1162
Parameters:
1163
- user_id: User identifier to remove
1164
- request_options: Additional request options
1165
1166
Returns:
1167
RemoveUserIdResponse with removal confirmation
1168
"""
1169
1170
async def search_user_ids(
1171
self,
1172
search_user_ids_params: Union[SearchUserIdsParams, dict],
1173
request_options: Optional[Union[dict, RequestOptions]] = None
1174
) -> SearchUserIdsResponse:
1175
"""
1176
Search for user IDs matching criteria.
1177
1178
Parameters:
1179
- search_user_ids_params: Search parameters
1180
- request_options: Additional request options
1181
1182
Returns:
1183
SearchUserIdsResponse with matching user IDs
1184
"""
1185
1186
async def get_top_user_ids(
1187
self,
1188
request_options: Optional[Union[dict, RequestOptions]] = None
1189
) -> GetTopUserIdsResponse:
1190
"""
1191
Get the most active user IDs.
1192
1193
Parameters:
1194
- request_options: Additional request options
1195
1196
Returns:
1197
GetTopUserIdsResponse with top user IDs
1198
"""
1199
```
1200
1201
### Dictionary Operations
1202
1203
Manage custom dictionaries for enhanced search functionality.
1204
1205
```python { .api }
1206
async def get_dictionary_languages(
1207
self,
1208
request_options: Optional[Union[dict, RequestOptions]] = None
1209
) -> Dict[str, Languages]:
1210
"""
1211
Get available dictionary languages.
1212
1213
Parameters:
1214
- request_options: Additional request options
1215
1216
Returns:
1217
Dictionary of available languages
1218
"""
1219
1220
async def get_dictionary_settings(
1221
self,
1222
request_options: Optional[Union[dict, RequestOptions]] = None
1223
) -> GetDictionarySettingsResponse:
1224
"""
1225
Get current dictionary settings.
1226
1227
Parameters:
1228
- request_options: Additional request options
1229
1230
Returns:
1231
GetDictionarySettingsResponse with settings
1232
"""
1233
1234
async def set_dictionary_settings(
1235
self,
1236
dictionary_settings_params: Union[DictionarySettingsParams, dict],
1237
request_options: Optional[Union[dict, RequestOptions]] = None
1238
) -> UpdatedAtResponse:
1239
"""
1240
Update dictionary settings.
1241
1242
Parameters:
1243
- dictionary_settings_params: New dictionary settings
1244
- request_options: Additional request options
1245
1246
Returns:
1247
UpdatedAtResponse with update confirmation
1248
"""
1249
1250
async def search_dictionary_entries(
1251
self,
1252
dictionary_name: Union[DictionaryType, str],
1253
search_dictionary_entries_params: Union[SearchDictionaryEntriesParams, dict],
1254
request_options: Optional[Union[dict, RequestOptions]] = None
1255
) -> SearchDictionaryEntriesResponse:
1256
"""
1257
Search for entries in a dictionary.
1258
1259
Parameters:
1260
- dictionary_name: Dictionary type to search
1261
- search_dictionary_entries_params: Search parameters
1262
- request_options: Additional request options
1263
1264
Returns:
1265
SearchDictionaryEntriesResponse with matching entries
1266
"""
1267
1268
async def batch_dictionary_entries(
1269
self,
1270
dictionary_name: Union[DictionaryType, str],
1271
batch_dictionary_entries_params: Union[BatchDictionaryEntriesParams, dict],
1272
request_options: Optional[Union[dict, RequestOptions]] = None
1273
) -> UpdatedAtResponse:
1274
"""
1275
Perform batch operations on dictionary entries.
1276
1277
Parameters:
1278
- dictionary_name: Dictionary type to modify
1279
- batch_dictionary_entries_params: Batch operations to perform
1280
- request_options: Additional request options
1281
1282
Returns:
1283
UpdatedAtResponse with operation confirmation
1284
"""
1285
```
1286
1287
### Custom Operations
1288
1289
Perform custom HTTP operations on the Algolia API.
1290
1291
```python { .api }
1292
async def custom_get(
1293
self,
1294
path: str,
1295
parameters: Optional[Dict[str, Any]] = None,
1296
request_options: Optional[Union[dict, RequestOptions]] = None
1297
) -> object:
1298
"""
1299
Perform a custom GET request.
1300
1301
Parameters:
1302
- path: API endpoint path after "/1"
1303
- parameters: Query parameters
1304
- request_options: Additional request options
1305
1306
Returns:
1307
Response object
1308
"""
1309
1310
async def custom_post(
1311
self,
1312
path: str,
1313
parameters: Optional[Dict[str, Any]] = None,
1314
body: Optional[Dict[str, Any]] = None,
1315
request_options: Optional[Union[dict, RequestOptions]] = None
1316
) -> object:
1317
"""
1318
Perform a custom POST request.
1319
1320
Parameters:
1321
- path: API endpoint path after "/1"
1322
- parameters: Query parameters
1323
- body: Request body data
1324
- request_options: Additional request options
1325
1326
Returns:
1327
Response object
1328
"""
1329
1330
async def custom_put(
1331
self,
1332
path: str,
1333
parameters: Optional[Dict[str, Any]] = None,
1334
body: Optional[Dict[str, Any]] = None,
1335
request_options: Optional[Union[dict, RequestOptions]] = None
1336
) -> object:
1337
"""
1338
Perform a custom PUT request.
1339
1340
Parameters:
1341
- path: API endpoint path after "/1"
1342
- parameters: Query parameters
1343
- body: Request body data
1344
- request_options: Additional request options
1345
1346
Returns:
1347
Response object
1348
"""
1349
1350
async def custom_delete(
1351
self,
1352
path: str,
1353
parameters: Optional[Dict[str, Any]] = None,
1354
request_options: Optional[Union[dict, RequestOptions]] = None
1355
) -> object:
1356
"""
1357
Perform a custom DELETE request.
1358
1359
Parameters:
1360
- path: API endpoint path after "/1"
1361
- parameters: Query parameters
1362
- request_options: Additional request options
1363
1364
Returns:
1365
Response object
1366
"""
1367
1368
## Usage Examples
1369
1370
### Basic Search and Object Management
1371
1372
```python
1373
from algoliasearch.search.client import SearchClient
1374
1375
# Initialize client
1376
client = SearchClient("YOUR_APP_ID", "YOUR_API_KEY")
1377
1378
# Save objects to an index
1379
products = [
1380
{"objectID": "1", "name": "iPhone 13", "brand": "Apple", "price": 699},
1381
{"objectID": "2", "name": "Galaxy S21", "brand": "Samsung", "price": 649}
1382
]
1383
1384
# Save objects with automatic chunking
1385
responses = await client.save_objects(
1386
index_name="products",
1387
objects=products,
1388
wait_for_tasks=True
1389
)
1390
1391
# Search for products
1392
search_response = await client.search({
1393
"requests": [{
1394
"indexName": "products",
1395
"query": "iPhone",
1396
"hitsPerPage": 10,
1397
"filters": "price < 800"
1398
}]
1399
})
1400
1401
# Display results
1402
for hit in search_response.results[0].hits:
1403
print(f"{hit['name']} - ${hit['price']}")
1404
```
1405
1406
### Advanced Search with Rules and Synonyms
1407
1408
```python
1409
# Create a search rule for merchandising
1410
rule = {
1411
"objectID": "promo-rule",
1412
"condition": {
1413
"pattern": "smartphone",
1414
"anchoring": "contains"
1415
},
1416
"consequence": {
1417
"promote": [
1418
{"objectID": "1", "position": 0}
1419
]
1420
},
1421
"description": "Promote iPhone for smartphone queries"
1422
}
1423
1424
# Save the rule
1425
await client.save_rule(
1426
index_name="products",
1427
object_id="promo-rule",
1428
rule=rule
1429
)
1430
1431
# Create synonyms for better search
1432
synonym = {
1433
"objectID": "phone-synonyms",
1434
"type": "synonym",
1435
"synonyms": ["phone", "mobile", "smartphone", "cellphone"]
1436
}
1437
1438
# Save the synonym
1439
await client.save_synonym(
1440
index_name="products",
1441
object_id="phone-synonyms",
1442
synonym_hit=synonym
1443
)
1444
```
1445
1446
### Batch Operations and Index Management
1447
1448
```python
1449
# Replace all objects atomically
1450
new_products = [
1451
{"objectID": "3", "name": "iPad Pro", "brand": "Apple", "price": 1099},
1452
{"objectID": "4", "name": "Surface Pro", "brand": "Microsoft", "price": 999}
1453
]
1454
1455
# This preserves settings, rules, and synonyms while replacing all objects
1456
replace_response = await client.replace_all_objects(
1457
index_name="products",
1458
objects=new_products,
1459
batch_size=1000
1460
)
1461
1462
# Configure index settings
1463
settings = {
1464
"searchableAttributes": ["name", "brand", "description"],
1465
"attributesForFaceting": ["brand", "category", "price"],
1466
"customRanking": ["desc(popularity)", "asc(price)"],
1467
"ranking": ["typo", "geo", "words", "filters", "proximity", "attribute", "exact", "custom"]
1468
}
1469
1470
await client.set_settings(
1471
index_name="products",
1472
index_settings=settings
1473
)
1474
```
1475
1476
## Types
1477
1478
```python { .api }
1479
# Core request/response types
1480
class SearchMethodParams(BaseModel):
1481
requests: List[SearchParams]
1482
1483
class SearchParams(BaseModel):
1484
index_name: str
1485
query: Optional[str] = None
1486
hits_per_page: Optional[int] = None
1487
page: Optional[int] = None
1488
filters: Optional[str] = None
1489
facet_filters: Optional[List[str]] = None
1490
numeric_filters: Optional[List[str]] = None
1491
around_lat_lng: Optional[str] = None
1492
around_radius: Optional[int] = None
1493
1494
class SearchResponse(BaseModel):
1495
results: List[SearchResult]
1496
1497
class SearchResult(BaseModel):
1498
hits: List[dict]
1499
nb_hits: int
1500
page: int
1501
nb_pages: int
1502
hits_per_page: int
1503
processing_time_ms: int
1504
exhaustive_nb_hits: bool
1505
query: str
1506
params: str
1507
1508
# Index settings
1509
class IndexSettings(BaseModel):
1510
searchable_attributes: Optional[List[str]] = None
1511
attributes_for_faceting: Optional[List[str]] = None
1512
unretrievable_attributes: Optional[List[str]] = None
1513
attributes_to_retrieve: Optional[List[str]] = None
1514
ranking: Optional[List[str]] = None
1515
custom_ranking: Optional[List[str]] = None
1516
replicas: Optional[List[str]] = None
1517
max_values_per_facet: Optional[int] = None
1518
sort_facet_values_by: Optional[str] = None
1519
1520
# API Key types
1521
class ApiKey(BaseModel):
1522
acl: List[str]
1523
description: Optional[str] = None
1524
indices: Optional[List[str]] = None
1525
max_hits_per_query: Optional[int] = None
1526
max_queries_per_ip_per_hour: Optional[int] = None
1527
query_parameters: Optional[str] = None
1528
referers: Optional[List[str]] = None
1529
validity: Optional[int] = None
1530
1531
class SecuredApiKeyRestrictions(BaseModel):
1532
valid_until: Optional[int] = None
1533
restrict_indices: Optional[List[str]] = None
1534
restrict_sources: Optional[str] = None
1535
filter: Optional[str] = None
1536
user_token: Optional[str] = None
1537
1538
# Rules
1539
class Rule(BaseModel):
1540
object_id: str
1541
condition: dict
1542
consequence: dict
1543
description: Optional[str] = None
1544
enabled: Optional[bool] = None
1545
1546
# Synonyms
1547
class SynonymHit(BaseModel):
1548
object_id: str
1549
type: str
1550
synonyms: Optional[List[str]] = None
1551
input: Optional[str] = None
1552
word: Optional[str] = None
1553
corrections: Optional[List[str]] = None
1554
1555
# Batch operations
1556
class BatchWriteParams(BaseModel):
1557
requests: List[dict]
1558
1559
class BatchParams(BaseModel):
1560
requests: List[dict]
1561
1562
class Action(str, Enum):
1563
ADDOBJECT = "addObject"
1564
UPDATEOBJECT = "updateObject"
1565
PARTIALUPDATEOBJECT = "partialUpdateObject"
1566
DELETEOBJECT = "deleteObject"
1567
1568
# User ID types
1569
class AssignUserIdParams(BaseModel):
1570
cluster: str
1571
1572
class UserId(BaseModel):
1573
user_id: str
1574
cluster_name: str
1575
nb_records: int
1576
data_size: int
1577
1578
# Dictionary types
1579
class DictionaryType(str, Enum):
1580
STOPWORDS = "stopwords"
1581
PLURALS = "plurals"
1582
COMPOUNDS = "compounds"
1583
1584
class Languages(BaseModel):
1585
nb_custom_entries: int
1586
1587
# Response types
1588
class SaveObjectResponse(BaseModel):
1589
created_at: str
1590
task_id: int
1591
object_id: str
1592
1593
class SaveSynonymResponse(BaseModel):
1594
updated_at: str
1595
task_id: int
1596
id: str
1597
1598
class MultipleBatchResponse(BaseModel):
1599
task_id: Dict[str, int]
1600
object_ids: List[str]
1601
1602
class ReplaceAllObjectsResponse(BaseModel):
1603
copy_operation_response: UpdatedAtResponse
1604
batch_responses: List[BatchResponse]
1605
move_operation_response: UpdatedAtResponse
1606
1607
class IngestionWatchResponse(BaseModel):
1608
task_id: int
1609
watched_objects: List[dict]
1610
1611
class DeleteByParams(BaseModel):
1612
filters: Optional[str] = None
1613
numeric_filters: Optional[List[str]] = None
1614
facet_filters: Optional[List[str]] = None
1615
around_lat_lng: Optional[str] = None
1616
around_radius: Optional[int] = None
1617
1618
class SearchDictionaryEntriesParams(BaseModel):
1619
query: Optional[str] = None
1620
page: Optional[int] = None
1621
hits_per_page: Optional[int] = None
1622
1623
class BatchDictionaryEntriesParams(BaseModel):
1624
clear_existing_dictionary_entries: Optional[bool] = None
1625
requests: List[dict]
1626
1627
class SearchUserIdsParams(BaseModel):
1628
query: Optional[str] = None
1629
cluster_name: Optional[str] = None
1630
page: Optional[int] = None
1631
hits_per_page: Optional[int] = None
1632
```