Skip to content

Client

client Usage

Create a client

To create a client:

from milisearch_python_sdk import Client


client = Client("http://localhost:7700", "masterKey")
index = client.index("movies")
...

Custom headers

Custom headers can be added to the client by adding them to custom_headers when creating the client.

from meilisearch_python_sdk import Client

client = Client(
    "http://127.0.0.1:7700",
    "masterKey",
    custom_headers={"header_key_1": "header_value_1", "header_key_2": "header_value_2"}
)
index = client.index("movies")
...

Client API

Bases: BaseClient

client to connect to the Meilisearch API.

Source code in meilisearch_python_sdk/_client.py
 990
 991
 992
 993
 994
 995
 996
 997
 998
 999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
class Client(BaseClient):
    """client to connect to the Meilisearch API."""

    def __init__(
        self,
        url: str,
        api_key: str | None = None,
        *,
        timeout: int | None = None,
        verify: bool | SSLContext = True,
        custom_headers: dict[str, str] | None = None,
        json_handler: BuiltinHandler | OrjsonHandler | UjsonHandler | None = None,
        http2: bool = False,
    ) -> None:
        """Class initializer.

        Args:
            url: The url to the Meilisearch API (ex: http://localhost:7700)
            api_key: The optional API key for Meilisearch. Defaults to None.
            timeout: The amount of time in seconds that the client will wait for a response before
                timing out. Defaults to None.
            verify: SSL certificates (a.k.a CA bundle) used to
                verify the identity of requested hosts. Either `True` (default CA bundle),
                a path to an SSL certificate file, or `False` (disable verification)
            custom_headers: Custom headers to add when sending data to Meilisearch. Defaults to
                None.
            json_handler: The module to use for json operations. The options are BuiltinHandler
                (uses the json module from the standard library), OrjsonHandler (uses orjson), or
                UjsonHandler (uses ujson). Note that in order use orjson or ujson the corresponding
                extra needs to be included. Default: BuiltinHandler.
            http2: If set to True, the client will use HTTP/2. Defaults to False.
        """
        super().__init__(api_key, custom_headers, json_handler)

        self.http_client = HttpxClient(
            base_url=url, timeout=timeout, headers=self._headers, verify=verify, http2=http2
        )

        self._http_requests = HttpRequests(self.http_client, json_handler=self.json_handler)

    def create_dump(self) -> TaskInfo:
        """Trigger the creation of a Meilisearch dump.

        Returns:
            The details of the task.

        Raises:
            MeilisearchCommunicationError: If there was an error communicating with the server.
            MeilisearchApiError: If the Meilisearch API returned an error.

        Examples
            >>> from meilisearch_python_sdk import Client
            >>> client = Client("http://localhost.com", "masterKey")
            >>> client.create_dump()
        """
        response = self._http_requests.post("dumps")

        return TaskInfo(**response.json())

    def create_index(
        self,
        uid: str,
        primary_key: str | None = None,
        *,
        settings: MeilisearchSettings | None = None,
        wait: bool = True,
        timeout_in_ms: int | None = None,
        plugins: IndexPlugins | None = None,
        hits_type: Any = JsonDict,
    ) -> Index:
        """Creates a new index.

        Args:
            uid: The index's unique identifier.
            primary_key: The primary key of the documents. Defaults to None.
            settings: Settings for the index. The settings can also be updated independently of
                creating the index. The advantage to updating them here is updating the settings after
                adding documents will cause the documents to be re-indexed. Because of this it will be
                faster to update them before adding documents. Defaults to None (i.e. default
                Meilisearch index settings).
            wait: If set to True and settings are being updated, the index will be returned after
                the settings update has completed. If False it will not wait for settings to complete.
                Default: True
            timeout_in_ms: Amount of time in milliseconds to wait before raising a
                MeilisearchTimeoutError. `None` can also be passed to wait indefinitely. Be aware that
                if the `None` option is used the wait time could be very long. Defaults to None.
            plugins: Optional plugins can be provided to extend functionality.
            hits_type: Allows for a custom type to be passed to use for hits. Defaults to
                JsonDict

        Returns:
            An instance of Index containing the information of the newly created index.

        Raises:
            MeilisearchCommunicationError: If there was an error communicating with the server.
            MeilisearchApiError: If the Meilisearch API returned an error.

        Examples
            >>> from meilisearch_python_sdk import Client
            >>> client = Client("http://localhost.com", "masterKey")
            >>> index = client.create_index("movies")
        """
        return Index.create(
            self.http_client,
            uid,
            primary_key,
            settings=settings,
            wait=wait,
            timeout_in_ms=timeout_in_ms,
            plugins=plugins,
            json_handler=self.json_handler,
            hits_type=hits_type,
        )

    def create_snapshot(self) -> TaskInfo:
        """Trigger the creation of a Meilisearch snapshot.

        Returns:
            The details of the task.

        Raises:
            MeilisearchCommunicationError: If there was an error communicating with the server.
            MeilisearchApiError: If the Meilisearch API returned an error.

        Examples
            >>> from meilisearch_python_sdk import Client
            >>> client = Client("http://localhost.com", "masterKey")
            >>> client.create_snapshot()
        """
        response = self._http_requests.post("snapshots")

        return TaskInfo(**response.json())

    def delete_index_if_exists(self, uid: str) -> bool:
        """Deletes an index if it already exists.

        Args:
            uid: The index's unique identifier.

        Returns:
            True if an index was deleted for False if not.

        Raises:
            MeilisearchCommunicationError: If there was an error communicating with the server.
            MeilisearchApiError: If the Meilisearch API returned an error.

        Examples
            >>> from meilisearch_python_sdk import Client
            >>> client = Client("http://localhost.com", "masterKey")
            >>> client.delete_index_if_exists()
        """
        response = self._http_requests.delete(f"indexes/{uid}")
        status = self.wait_for_task(response.json()["taskUid"], timeout_in_ms=100000)
        if status.status == "succeeded":
            return True
        return False

    def get_indexes(
        self, *, offset: int | None = None, limit: int | None = None
    ) -> list[Index] | None:
        """Get all indexes.
        Args:
            offset: Number of indexes to skip. The default of None will use the Meilisearch
                default.
            limit: Number of indexes to return. The default of None will use the Meilisearch
                default.

        Returns:
            A list of all indexes.

        Raises:
            MeilisearchCommunicationError: If there was an error communicating with the server.
            MeilisearchApiError: If the Meilisearch API returned an error.

        Examples
            >>> from meilisearch_python_sdk import Client
            >>> client = Client("http://localhost.com", "masterKey") as client:
            >>> indexes = client.get_indexes()
        """
        url = _build_offset_limit_url("indexes", offset, limit)
        response = self._http_requests.get(url)

        if not response.json()["results"]:
            return None

        return [
            Index(
                http_client=self.http_client,
                uid=x["uid"],
                primary_key=x["primaryKey"],
                created_at=x["createdAt"],
                updated_at=x["updatedAt"],
                json_handler=self.json_handler,
            )
            for x in response.json()["results"]
        ]

    def get_index(self, uid: str) -> Index:
        """Gets a single index based on the uid of the index.

        Args:
            uid: The index's unique identifier.

        Returns:
            An Index instance containing the information of the fetched index.

        Raises:
            MeilisearchCommunicationError: If there was an error communicating with the server.
            MeilisearchApiError: If the Meilisearch API returned an error.

        Examples
            >>> from meilisearch_python_sdk import Client
            >>> client = Client("http://localhost.com", "masterKey")
            >>> index = client.get_index()
        """
        return Index(self.http_client, uid, json_handler=self.json_handler).fetch_info()

    def index(self, uid: str, *, plugins: IndexPlugins | None = None) -> Index:
        """Create a local reference to an index identified by UID, without making an HTTP call.

        Args:
            uid: The index's unique identifier.
            plugins: Optional plugins can be provided to extend functionality.

        Returns:
            An Index instance.

        Raises:
            MeilisearchCommunicationError: If there was an error communicating with the server.
            MeilisearchApiError: If the Meilisearch API returned an error.

        Examples
            >>> from meilisearch_python_sdk import Client
            >>> client = Client("http://localhost.com", "masterKey")
            >>> index = client.index("movies")
        """
        return Index(self.http_client, uid=uid, plugins=plugins, json_handler=self.json_handler)

    def get_all_stats(self) -> ClientStats:
        """Get stats for all indexes.

        Returns:
            Information about database size and all indexes.
            https://docs.meilisearch.com/reference/api/stats.html

        Raises:
            MeilisearchCommunicationError: If there was an error communicating with the server.
            MeilisearchApiError: If the Meilisearch API returned an error.

        Examples
            >>> from meilisearch_python_sdk import Client
            >>> client = Client("http://localhost.com", "masterKey")
            >>> stats = client.get_all_stats()
        """
        response = self._http_requests.get("stats")

        return ClientStats(**response.json())

    def get_or_create_index(
        self,
        uid: str,
        primary_key: str | None = None,
        *,
        plugins: IndexPlugins | None = None,
        hits_type: Any = JsonDict,
    ) -> Index:
        """Get an index, or create it if it doesn't exist.

        Args:
            uid: The index's unique identifier.
            primary_key: The primary key of the documents. Defaults to None.
            plugins: Optional plugins can be provided to extend functionality.
            hits_type: Allows for a custom type to be passed to use for hits. Defaults to
                JsonDict

        Returns:
            An instance of Index containing the information of the retrieved or newly created index.

        Raises:
            MeilisearchCommunicationError: If there was an error communicating with the server.
            MeilisearchApiError: If the Meilisearch API returned an error.MeilisearchTimeoutError: If the connection times out.
            MeilisearchTimeoutError: If the connection times out.

        Examples
            >>> from meilisearch_python_sdk import Client
            >>> client = Client("http://localhost.com", "masterKey")
            >>> index = client.get_or_create_index("movies")
        """
        try:
            index_instance = self.get_index(uid)
        except MeilisearchApiError as err:
            if "index_not_found" not in err.code:
                raise
            index_instance = self.create_index(
                uid, primary_key, plugins=plugins, hits_type=hits_type
            )
        return index_instance

    def create_key(self, key: KeyCreate) -> Key:
        """Creates a new API key.

        Args:
            key: The information to use in creating the key. Note that if an expires_at value
                is included it should be in UTC time.

        Returns:
            The new API key.

        Raises:
            MeilisearchCommunicationError: If there was an error communicating with the server.
            MeilisearchApiError: If the Meilisearch API returned an error.

        Examples
            >>> from meilisearch_python_sdk import Client
            >>> from meilissearch_async_client.models.client import KeyCreate
            >>> client = Client("http://localhost.com", "masterKey")
            >>> key_info = KeyCreate(
            >>>     description="My new key",
            >>>     actions=["search"],
            >>>     indexes=["movies"],
            >>> )
            >>> keys = client.create_key(key_info)
        """
        response = self._http_requests.post(
            "keys", self.json_handler.loads(key.model_dump_json(by_alias=True))
        )  # type: ignore[attr-defined]

        return Key(**response.json())

    def delete_key(self, key: str) -> int:
        """Deletes an API key.

        Args:
            key: The key or uid to delete.

        Returns:
            The Response status code. 204 signifies a successful delete.

        Raises:
            MeilisearchCommunicationError: If there was an error communicating with the server.
            MeilisearchApiError: If the Meilisearch API returned an error.

        Examples
            >>> from meilisearch_python_sdk import Client
            >>> client = Client("http://localhost.com", "masterKey")
            >>> client.delete_key("abc123")
        """
        response = self._http_requests.delete(f"keys/{key}")
        return response.status_code

    def get_keys(self, *, offset: int | None = None, limit: int | None = None) -> KeySearch:
        """Gets the Meilisearch API keys.
        Args:
            offset: Number of indexes to skip. The default of None will use the Meilisearch
                default.
            limit: Number of indexes to return. The default of None will use the Meilisearch
                default.

        Returns:
            API keys.

        Raises:
            MeilisearchCommunicationError: If there was an error communicating with the server.
            MeilisearchApiError: If the Meilisearch API returned an error.

        Examples
            >>> from meilisearch_python_sdk import Client
            >>> client = AsyncClient("http://localhost.com", "masterKey")
            >>> keys = client.get_keys()
        """
        url = _build_offset_limit_url("keys", offset, limit)
        response = self._http_requests.get(url)

        return KeySearch(**response.json())

    def get_key(self, key: str) -> Key:
        """Gets information about a specific API key.

        Args:
            key: The key for which to retrieve the information.

        Returns:
            The API key, or `None` if the key is not found.

        Raises:
            MeilisearchCommunicationError: If there was an error communicating with the server.
            MeilisearchApiError: If the Meilisearch API returned an error.

        Examples
            >>> from meilisearch_python_sdk import Client
            >>> client = Client("http://localhost.com", "masterKey")
            >>> keys = client.get_key("abc123")
        """
        response = self._http_requests.get(f"keys/{key}")

        return Key(**response.json())

    def update_key(self, key: KeyUpdate) -> Key:
        """Update an API key.

        Args:
            key: The information to use in updating the key. Note that if an expires_at value
                is included it should be in UTC time.

        Returns:
            The updated API key.

        Raises:
            MeilisearchCommunicationError: If there was an error communicating with the server.
            MeilisearchApiError: If the Meilisearch API returned an error.

        Examples
            >>> from meilisearch_python_sdk import Client
            >>> from meilissearch_async_client.models.client import KeyUpdate
            >>> client = Client("http://localhost.com", "masterKey")
            >>> key_info = KeyUpdate(
                    key="abc123",
            >>>     indexes=["*"],
            >>> )
            >>> keys = client.update_key(key_info)
        """
        payload = _build_update_key_payload(key, self.json_handler)
        response = self._http_requests.patch(f"keys/{key.key}", payload)

        return Key(**response.json())

    def multi_search(
        self,
        queries: list[SearchParams],
        *,
        federation: Federation | FederationMerged | None = None,
        hits_type: Any = JsonDict,
    ) -> list[SearchResultsWithUID] | SearchResultsFederated:
        """Multi-index search.

        Args:
            queries: List of SearchParameters
            federation: If included a single search result with hits built from all queries will
                be returned. This parameter can only be used with Meilisearch >= v1.10.0. Defaults
                to None.
            hits_type: Allows for a custom type to be passed to use for hits. Defaults to
                JsonDict

        Returns:
            Results of the search

        Raises:
            MeilisearchCommunicationError: If there was an error communicating with the server.
            MeilisearchApiError: If the Meilisearch API returned an error.

        Examples
            >>> from meilisearch_python_sdk import Client
            >>> from meilisearch_python_sdk.models.search import SearchParams
            >>> client = Client("http://localhost.com", "masterKey")
            >>> queries = [
            >>>     SearchParams(index_uid="my_first_index", query"Some search"),
            >>>     SearchParams(index_uid="my_second_index", query="Another search")
            >>> ]
            >>> search_results = client.search(queries)
        """
        url = "multi-search"
        if federation:
            processed_queries = []
            for query in queries:
                q = query.model_dump(by_alias=True)
                del q["limit"]
                del q["offset"]
                processed_queries.append(q)
        else:
            processed_queries = [x.model_dump(by_alias=True) for x in queries]

        if federation:
            federation_payload = federation.model_dump(by_alias=True)
            if federation.facets_by_index is None:
                del federation_payload["facetsByIndex"]

        else:
            federation_payload = None

        response = self._http_requests.post(
            url,
            body={
                "federation": federation_payload,
                "queries": processed_queries,
            },
        )

        if federation:
            results = response.json()
            return SearchResultsFederated[hits_type](**results)

        return [SearchResultsWithUID[hits_type](**x) for x in response.json()["results"]]

    def get_raw_index(self, uid: str) -> IndexInfo | None:
        """Gets the index and returns all the index information rather than an Index instance.

        Args:
            uid: The index's unique identifier.

        Returns:
            Index information rather than an Index instance.

        Raises:
            MeilisearchCommunicationError: If there was an error communicating with the server.
            MeilisearchApiError: If the Meilisearch API returned an error.

        Examples
            >>> from meilisearch_python_sdk import Client
            >>> client = Client("http://localhost.com", "masterKey")
            >>> index = client.get_raw_index("movies")
        """
        response = self.http_client.get(f"indexes/{uid}")

        if response.status_code == 404:
            return None

        return IndexInfo(**response.json())

    def get_raw_indexes(
        self, *, offset: int | None = None, limit: int | None = None
    ) -> list[IndexInfo] | None:
        """Gets all the indexes.
        Args:
            offset: Number of indexes to skip. The default of None will use the Meilisearch
                default.
            limit: Number of indexes to return. The default of None will use the Meilisearch
                default.

        Returns all the index information rather than an AsyncIndex instance.

        Returns:
            A list of the Index information rather than an AsyncIndex instances.

        Raises:
            MeilisearchCommunicationError: If there was an error communicating with the server.
            MeilisearchApiError: If the Meilisearch API returned an error.

        Examples
            >>> from meilisearch_python_sdk import Client
            >>> client = Client("http://localhost.com", "masterKey")
            >>> index = client.get_raw_indexes()
        """
        url = _build_offset_limit_url("indexes", offset, limit)
        response = self._http_requests.get(url)

        if not response.json()["results"]:
            return None

        return [IndexInfo(**x) for x in response.json()["results"]]

    def get_version(self) -> Version:
        """Get the Meilisearch version.

        Returns:
            Information about the version of Meilisearch.

        Raises:
            MeilisearchCommunicationError: If there was an error communicating with the server.
            MeilisearchApiError: If the Meilisearch API returned an error.

        Examples
            >>> from meilisearch_python_sdk import Client
            >>> client = Client("http://localhost.com", "masterKey")
            >>> version = client.get_version()
        """
        response = self._http_requests.get("version")

        return Version(**response.json())

    def health(self) -> Health:
        """Get health of the Meilisearch server.

        Returns:
            The status of the Meilisearch server.

        Raises:
            MeilisearchCommunicationError: If there was an error communicating with the server.
            MeilisearchApiError: If the Meilisearch API returned an error.

        Examples
            >>> from meilisearch_python_sdk import Client
            >>> client = Client("http://localhost.com", "masterKey")
            >>> health = client.get_health()
        """
        response = self._http_requests.get("health")

        return Health(**response.json())

    def swap_indexes(self, indexes: list[tuple[str, str]]) -> TaskInfo:
        """Swap two indexes.

        Args:
            indexes: A list of tuples, each tuple should contain the indexes to swap.

        Returns:
            The details of the task.

        Raises:
            MeilisearchCommunicationError: If there was an error communicating with the server.
            MeilisearchApiError: If the Meilisearch API returned an error.

        Examples
            >>> from meilisearch_python_sdk import Client
            >>> client = Client("http://localhost.com", "masterKey")
            >>> index = client.swap_indexes([("index_a", "index_b")])
        """
        processed_indexes = [{"indexes": x} for x in indexes]
        response = self._http_requests.post("swap-indexes", processed_indexes)

        return TaskInfo(**response.json())

    def get_batch(self, batch_uid: int) -> BatchResult | None:
        return get_batch(self, batch_uid)

    def get_batches(self) -> BatchStatus:
        return get_batches(self)

    def cancel_tasks(
        self,
        *,
        uids: list[str] | None = None,
        index_uids: list[str] | None = None,
        statuses: list[str] | None = None,
        types: list[str] | None = None,
        before_enqueued_at: datetime | None = None,
        after_enqueued_at: datetime | None = None,
        before_started_at: datetime | None = None,
        after_finished_at: datetime | None = None,
    ) -> TaskInfo:
        """Cancel a list of enqueued or processing tasks.

        Defaults to cancelling all tasks.

        Args:
            uids: A list of task UIDs to cancel.
            index_uids: A list of index UIDs for which to cancel tasks.
            statuses: A list of statuses to cancel.
            types: A list of types to cancel.
            before_enqueued_at: Cancel tasks that were enqueued before the specified date time.
            after_enqueued_at: Cancel tasks that were enqueued after the specified date time.
            before_started_at: Cancel tasks that were started before the specified date time.
            after_finished_at: Cancel tasks that were finished after the specified date time.

        Returns:
            The details of the task

        Raises:
            MeilisearchCommunicationError: If there was an error communicating with the server.
            MeilisearchApiError: If the Meilisearch API returned an error.
            MeilisearchTimeoutError: If the connection times out.

        Examples
            >>> from meilisearch_python_sdk import Client
            >>> from meilisearch_python_sdk.task import cancel_tasks
            >>>
            >>> client = Client("http://localhost.com", "masterKey")
            >>> client.cancel_tasks(uids=[1, 2])
        """
        return _task.cancel_tasks(
            self.http_client,
            uids=uids,
            index_uids=index_uids,
            statuses=statuses,
            types=types,
            before_enqueued_at=before_enqueued_at,
            after_enqueued_at=after_enqueued_at,
            before_started_at=before_started_at,
            after_finished_at=after_finished_at,
        )

    def delete_tasks(
        self,
        *,
        uids: list[str] | None = None,
        index_uids: list[str] | None = None,
        statuses: list[str] | None = None,
        types: list[str] | None = None,
        before_enqueued_at: datetime | None = None,
        after_enqueued_at: datetime | None = None,
        before_started_at: datetime | None = None,
        after_finished_at: datetime | None = None,
    ) -> TaskInfo:
        """Delete a list of tasks.

        Defaults to deleting all tasks.

        Args:
            uids: A list of task UIDs to delete.
            index_uids: A list of index UIDs for which to delete tasks.
            statuses: A list of statuses to delete.
            types: A list of types to delete.
            before_enqueued_at: Delete tasks that were enqueued before the specified date time.
            after_enqueued_at: Delete tasks that were enqueued after the specified date time.
            before_started_at: Delete tasks that were started before the specified date time.
            after_finished_at: Delete tasks that were finished after the specified date time.

        Returns:
            The details of the task

        Raises:
            MeilisearchCommunicationError: If there was an error communicating with the server.
            MeilisearchApiError: If the Meilisearch API returned an error.
            MeilisearchTimeoutError: If the connection times out.

        Examples
            >>> from meilisearch_python_sdk import Client
            >>>
            >>> client = Client("http://localhost.com", "masterKey")
            >>> client.delete_tasks(client, uids=[1, 2])
        """
        return _task.delete_tasks(
            self.http_client,
            uids=uids,
            index_uids=index_uids,
            statuses=statuses,
            types=types,
            before_enqueued_at=before_enqueued_at,
            after_enqueued_at=after_enqueued_at,
            before_started_at=before_started_at,
            after_finished_at=after_finished_at,
        )

    def get_task(self, task_id: int) -> TaskResult:
        """Get a single task from it's task id.

        Args:
            task_id: Identifier of the task to retrieve.

        Returns:
            Results of a task.

        Raises:
            MeilisearchCommunicationError: If there was an error communicating with the server.
            MeilisearchApiError: If the Meilisearch API returned an error.
            MeilisearchTimeoutError: If the connection times out.

        Examples
            >>> from meilisearch_python_sdk import Client
            >>>
            >>> client = AsyncClient("http://localhost.com", "masterKey")
            >>> get_task(client, 1244)
        """
        return _task.get_task(self.http_client, task_id=task_id)

    def get_tasks(
        self,
        *,
        index_ids: list[str] | None = None,
        types: str | list[str] | None = None,
        reverse: bool | None = None,
    ) -> TaskStatus:
        """Get multiple tasks.

        Args:
            index_ids: A list of index UIDs for which to get the tasks. If provided this will get the
                tasks only for the specified indexes, if not all tasks will be returned. Default = None
            types: Specify specific task types to retrieve. Default = None
            reverse: If True the tasks will be returned in reverse order. Default = None

        Returns:
            Task statuses.

        Raises:
            MeilisearchCommunicationError: If there was an error communicating with the server.
            MeilisearchApiError: If the Meilisearch API returned an error.
            MeilisearchTimeoutError: If the connection times out.

        Examples
            >>> from meilisearch_python_sdk import Client
            >>>
            >>> client = Client("http://localhost.com", "masterKey")
            >>> client.get_tasks(client)
        """
        return _task.get_tasks(self.http_client, index_ids=index_ids, types=types, reverse=reverse)

    def wait_for_task(
        self,
        task_id: int,
        *,
        timeout_in_ms: int | None = 5000,
        interval_in_ms: int = 50,
        raise_for_status: bool = False,
    ) -> TaskResult:
        """Wait until Meilisearch processes a task, and get its status.

        Args:
            task_id: Identifier of the task to retrieve.
            timeout_in_ms: Amount of time in milliseconds to wait before raising a
                MeilisearchTimeoutError. `None` can also be passed to wait indefinitely. Be aware that
                if the `None` option is used the wait time could be very long. Defaults to 5000.
            interval_in_ms: Time interval in miliseconds to sleep between requests. Defaults to 50.
            raise_for_status: When set to `True` a MeilisearchTaskFailedError will be raised if a task
                has a failed status. Defaults to False.

        Returns:
            Details of the processed update status.

        Raises:
            MeilisearchCommunicationError: If there was an error communicating with the server.
            MeilisearchApiError: If the Meilisearch API returned an error.
            MeilisearchTimeoutError: If the connection times out.
            MeilisearchTaskFailedError: If `raise_for_status` is `True` and a task has a failed status.

        Examples
            >>> from meilisearch_python_sdk import Client
            >>> >>> documents = [
            >>>     {"id": 1, "title": "Movie 1", "genre": "comedy"},
            >>>     {"id": 2, "title": "Movie 2", "genre": "drama"},
            >>> ]
            >>> client = Client("http://localhost.com", "masterKey")
            >>> index = client.index("movies")
            >>> response = await index.add_documents(documents)
            >>> client.wait_for_task(response.update_id)
        """
        return _task.wait_for_task(
            self.http_client,
            task_id=task_id,
            timeout_in_ms=timeout_in_ms,
            interval_in_ms=interval_in_ms,
            raise_for_status=raise_for_status,
        )

__init__(url, api_key=None, *, timeout=None, verify=True, custom_headers=None, json_handler=None, http2=False)

Class initializer.

Parameters:

Name Type Description Default
url str

The url to the Meilisearch API (ex: http://localhost:7700)

required
api_key str | None

The optional API key for Meilisearch. Defaults to None.

None
timeout int | None

The amount of time in seconds that the client will wait for a response before timing out. Defaults to None.

None
verify bool | SSLContext

SSL certificates (a.k.a CA bundle) used to verify the identity of requested hosts. Either True (default CA bundle), a path to an SSL certificate file, or False (disable verification)

True
custom_headers dict[str, str] | None

Custom headers to add when sending data to Meilisearch. Defaults to None.

None
json_handler BuiltinHandler | OrjsonHandler | UjsonHandler | None

The module to use for json operations. The options are BuiltinHandler (uses the json module from the standard library), OrjsonHandler (uses orjson), or UjsonHandler (uses ujson). Note that in order use orjson or ujson the corresponding extra needs to be included. Default: BuiltinHandler.

None
http2 bool

If set to True, the client will use HTTP/2. Defaults to False.

False
Source code in meilisearch_python_sdk/_client.py
 993
 994
 995
 996
 997
 998
 999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
def __init__(
    self,
    url: str,
    api_key: str | None = None,
    *,
    timeout: int | None = None,
    verify: bool | SSLContext = True,
    custom_headers: dict[str, str] | None = None,
    json_handler: BuiltinHandler | OrjsonHandler | UjsonHandler | None = None,
    http2: bool = False,
) -> None:
    """Class initializer.

    Args:
        url: The url to the Meilisearch API (ex: http://localhost:7700)
        api_key: The optional API key for Meilisearch. Defaults to None.
        timeout: The amount of time in seconds that the client will wait for a response before
            timing out. Defaults to None.
        verify: SSL certificates (a.k.a CA bundle) used to
            verify the identity of requested hosts. Either `True` (default CA bundle),
            a path to an SSL certificate file, or `False` (disable verification)
        custom_headers: Custom headers to add when sending data to Meilisearch. Defaults to
            None.
        json_handler: The module to use for json operations. The options are BuiltinHandler
            (uses the json module from the standard library), OrjsonHandler (uses orjson), or
            UjsonHandler (uses ujson). Note that in order use orjson or ujson the corresponding
            extra needs to be included. Default: BuiltinHandler.
        http2: If set to True, the client will use HTTP/2. Defaults to False.
    """
    super().__init__(api_key, custom_headers, json_handler)

    self.http_client = HttpxClient(
        base_url=url, timeout=timeout, headers=self._headers, verify=verify, http2=http2
    )

    self._http_requests = HttpRequests(self.http_client, json_handler=self.json_handler)

cancel_tasks(*, uids=None, index_uids=None, statuses=None, types=None, before_enqueued_at=None, after_enqueued_at=None, before_started_at=None, after_finished_at=None)

Cancel a list of enqueued or processing tasks.

Defaults to cancelling all tasks.

Parameters:

Name Type Description Default
uids list[str] | None

A list of task UIDs to cancel.

None
index_uids list[str] | None

A list of index UIDs for which to cancel tasks.

None
statuses list[str] | None

A list of statuses to cancel.

None
types list[str] | None

A list of types to cancel.

None
before_enqueued_at datetime | None

Cancel tasks that were enqueued before the specified date time.

None
after_enqueued_at datetime | None

Cancel tasks that were enqueued after the specified date time.

None
before_started_at datetime | None

Cancel tasks that were started before the specified date time.

None
after_finished_at datetime | None

Cancel tasks that were finished after the specified date time.

None

Returns:

Type Description
TaskInfo

The details of the task

Raises:

Type Description
MeilisearchCommunicationError

If there was an error communicating with the server.

MeilisearchApiError

If the Meilisearch API returned an error.

MeilisearchTimeoutError

If the connection times out.

Examples >>> from meilisearch_python_sdk import Client >>> from meilisearch_python_sdk.task import cancel_tasks >>> >>> client = Client("http://localhost.com", "masterKey") >>> client.cancel_tasks(uids=[1, 2])

Source code in meilisearch_python_sdk/_client.py
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
def cancel_tasks(
    self,
    *,
    uids: list[str] | None = None,
    index_uids: list[str] | None = None,
    statuses: list[str] | None = None,
    types: list[str] | None = None,
    before_enqueued_at: datetime | None = None,
    after_enqueued_at: datetime | None = None,
    before_started_at: datetime | None = None,
    after_finished_at: datetime | None = None,
) -> TaskInfo:
    """Cancel a list of enqueued or processing tasks.

    Defaults to cancelling all tasks.

    Args:
        uids: A list of task UIDs to cancel.
        index_uids: A list of index UIDs for which to cancel tasks.
        statuses: A list of statuses to cancel.
        types: A list of types to cancel.
        before_enqueued_at: Cancel tasks that were enqueued before the specified date time.
        after_enqueued_at: Cancel tasks that were enqueued after the specified date time.
        before_started_at: Cancel tasks that were started before the specified date time.
        after_finished_at: Cancel tasks that were finished after the specified date time.

    Returns:
        The details of the task

    Raises:
        MeilisearchCommunicationError: If there was an error communicating with the server.
        MeilisearchApiError: If the Meilisearch API returned an error.
        MeilisearchTimeoutError: If the connection times out.

    Examples
        >>> from meilisearch_python_sdk import Client
        >>> from meilisearch_python_sdk.task import cancel_tasks
        >>>
        >>> client = Client("http://localhost.com", "masterKey")
        >>> client.cancel_tasks(uids=[1, 2])
    """
    return _task.cancel_tasks(
        self.http_client,
        uids=uids,
        index_uids=index_uids,
        statuses=statuses,
        types=types,
        before_enqueued_at=before_enqueued_at,
        after_enqueued_at=after_enqueued_at,
        before_started_at=before_started_at,
        after_finished_at=after_finished_at,
    )

create_dump()

Trigger the creation of a Meilisearch dump.

Returns:

Type Description
TaskInfo

The details of the task.

Raises:

Type Description
MeilisearchCommunicationError

If there was an error communicating with the server.

MeilisearchApiError

If the Meilisearch API returned an error.

Examples >>> from meilisearch_python_sdk import Client >>> client = Client("http://localhost.com", "masterKey") >>> client.create_dump()

Source code in meilisearch_python_sdk/_client.py
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
def create_dump(self) -> TaskInfo:
    """Trigger the creation of a Meilisearch dump.

    Returns:
        The details of the task.

    Raises:
        MeilisearchCommunicationError: If there was an error communicating with the server.
        MeilisearchApiError: If the Meilisearch API returned an error.

    Examples
        >>> from meilisearch_python_sdk import Client
        >>> client = Client("http://localhost.com", "masterKey")
        >>> client.create_dump()
    """
    response = self._http_requests.post("dumps")

    return TaskInfo(**response.json())

create_index(uid, primary_key=None, *, settings=None, wait=True, timeout_in_ms=None, plugins=None, hits_type=JsonDict)

Creates a new index.

Parameters:

Name Type Description Default
uid str

The index's unique identifier.

required
primary_key str | None

The primary key of the documents. Defaults to None.

None
settings MeilisearchSettings | None

Settings for the index. The settings can also be updated independently of creating the index. The advantage to updating them here is updating the settings after adding documents will cause the documents to be re-indexed. Because of this it will be faster to update them before adding documents. Defaults to None (i.e. default Meilisearch index settings).

None
wait bool

If set to True and settings are being updated, the index will be returned after the settings update has completed. If False it will not wait for settings to complete. Default: True

True
timeout_in_ms int | None

Amount of time in milliseconds to wait before raising a MeilisearchTimeoutError. None can also be passed to wait indefinitely. Be aware that if the None option is used the wait time could be very long. Defaults to None.

None
plugins IndexPlugins | None

Optional plugins can be provided to extend functionality.

None
hits_type Any

Allows for a custom type to be passed to use for hits. Defaults to JsonDict

JsonDict

Returns:

Type Description
Index

An instance of Index containing the information of the newly created index.

Raises:

Type Description
MeilisearchCommunicationError

If there was an error communicating with the server.

MeilisearchApiError

If the Meilisearch API returned an error.

Examples >>> from meilisearch_python_sdk import Client >>> client = Client("http://localhost.com", "masterKey") >>> index = client.create_index("movies")

Source code in meilisearch_python_sdk/_client.py
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
def create_index(
    self,
    uid: str,
    primary_key: str | None = None,
    *,
    settings: MeilisearchSettings | None = None,
    wait: bool = True,
    timeout_in_ms: int | None = None,
    plugins: IndexPlugins | None = None,
    hits_type: Any = JsonDict,
) -> Index:
    """Creates a new index.

    Args:
        uid: The index's unique identifier.
        primary_key: The primary key of the documents. Defaults to None.
        settings: Settings for the index. The settings can also be updated independently of
            creating the index. The advantage to updating them here is updating the settings after
            adding documents will cause the documents to be re-indexed. Because of this it will be
            faster to update them before adding documents. Defaults to None (i.e. default
            Meilisearch index settings).
        wait: If set to True and settings are being updated, the index will be returned after
            the settings update has completed. If False it will not wait for settings to complete.
            Default: True
        timeout_in_ms: Amount of time in milliseconds to wait before raising a
            MeilisearchTimeoutError. `None` can also be passed to wait indefinitely. Be aware that
            if the `None` option is used the wait time could be very long. Defaults to None.
        plugins: Optional plugins can be provided to extend functionality.
        hits_type: Allows for a custom type to be passed to use for hits. Defaults to
            JsonDict

    Returns:
        An instance of Index containing the information of the newly created index.

    Raises:
        MeilisearchCommunicationError: If there was an error communicating with the server.
        MeilisearchApiError: If the Meilisearch API returned an error.

    Examples
        >>> from meilisearch_python_sdk import Client
        >>> client = Client("http://localhost.com", "masterKey")
        >>> index = client.create_index("movies")
    """
    return Index.create(
        self.http_client,
        uid,
        primary_key,
        settings=settings,
        wait=wait,
        timeout_in_ms=timeout_in_ms,
        plugins=plugins,
        json_handler=self.json_handler,
        hits_type=hits_type,
    )

create_key(key)

Creates a new API key.

Parameters:

Name Type Description Default
key KeyCreate

The information to use in creating the key. Note that if an expires_at value is included it should be in UTC time.

required

Returns:

Type Description
Key

The new API key.

Raises:

Type Description
MeilisearchCommunicationError

If there was an error communicating with the server.

MeilisearchApiError

If the Meilisearch API returned an error.

Examples >>> from meilisearch_python_sdk import Client >>> from meilissearch_async_client.models.client import KeyCreate >>> client = Client("http://localhost.com", "masterKey") >>> key_info = KeyCreate( >>> description="My new key", >>> actions=["search"], >>> indexes=["movies"], >>> ) >>> keys = client.create_key(key_info)

Source code in meilisearch_python_sdk/_client.py
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
def create_key(self, key: KeyCreate) -> Key:
    """Creates a new API key.

    Args:
        key: The information to use in creating the key. Note that if an expires_at value
            is included it should be in UTC time.

    Returns:
        The new API key.

    Raises:
        MeilisearchCommunicationError: If there was an error communicating with the server.
        MeilisearchApiError: If the Meilisearch API returned an error.

    Examples
        >>> from meilisearch_python_sdk import Client
        >>> from meilissearch_async_client.models.client import KeyCreate
        >>> client = Client("http://localhost.com", "masterKey")
        >>> key_info = KeyCreate(
        >>>     description="My new key",
        >>>     actions=["search"],
        >>>     indexes=["movies"],
        >>> )
        >>> keys = client.create_key(key_info)
    """
    response = self._http_requests.post(
        "keys", self.json_handler.loads(key.model_dump_json(by_alias=True))
    )  # type: ignore[attr-defined]

    return Key(**response.json())

create_snapshot()

Trigger the creation of a Meilisearch snapshot.

Returns:

Type Description
TaskInfo

The details of the task.

Raises:

Type Description
MeilisearchCommunicationError

If there was an error communicating with the server.

MeilisearchApiError

If the Meilisearch API returned an error.

Examples >>> from meilisearch_python_sdk import Client >>> client = Client("http://localhost.com", "masterKey") >>> client.create_snapshot()

Source code in meilisearch_python_sdk/_client.py
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
def create_snapshot(self) -> TaskInfo:
    """Trigger the creation of a Meilisearch snapshot.

    Returns:
        The details of the task.

    Raises:
        MeilisearchCommunicationError: If there was an error communicating with the server.
        MeilisearchApiError: If the Meilisearch API returned an error.

    Examples
        >>> from meilisearch_python_sdk import Client
        >>> client = Client("http://localhost.com", "masterKey")
        >>> client.create_snapshot()
    """
    response = self._http_requests.post("snapshots")

    return TaskInfo(**response.json())

delete_index_if_exists(uid)

Deletes an index if it already exists.

Parameters:

Name Type Description Default
uid str

The index's unique identifier.

required

Returns:

Type Description
bool

True if an index was deleted for False if not.

Raises:

Type Description
MeilisearchCommunicationError

If there was an error communicating with the server.

MeilisearchApiError

If the Meilisearch API returned an error.

Examples >>> from meilisearch_python_sdk import Client >>> client = Client("http://localhost.com", "masterKey") >>> client.delete_index_if_exists()

Source code in meilisearch_python_sdk/_client.py
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
def delete_index_if_exists(self, uid: str) -> bool:
    """Deletes an index if it already exists.

    Args:
        uid: The index's unique identifier.

    Returns:
        True if an index was deleted for False if not.

    Raises:
        MeilisearchCommunicationError: If there was an error communicating with the server.
        MeilisearchApiError: If the Meilisearch API returned an error.

    Examples
        >>> from meilisearch_python_sdk import Client
        >>> client = Client("http://localhost.com", "masterKey")
        >>> client.delete_index_if_exists()
    """
    response = self._http_requests.delete(f"indexes/{uid}")
    status = self.wait_for_task(response.json()["taskUid"], timeout_in_ms=100000)
    if status.status == "succeeded":
        return True
    return False

delete_key(key)

Deletes an API key.

Parameters:

Name Type Description Default
key str

The key or uid to delete.

required

Returns:

Type Description
int

The Response status code. 204 signifies a successful delete.

Raises:

Type Description
MeilisearchCommunicationError

If there was an error communicating with the server.

MeilisearchApiError

If the Meilisearch API returned an error.

Examples >>> from meilisearch_python_sdk import Client >>> client = Client("http://localhost.com", "masterKey") >>> client.delete_key("abc123")

Source code in meilisearch_python_sdk/_client.py
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
def delete_key(self, key: str) -> int:
    """Deletes an API key.

    Args:
        key: The key or uid to delete.

    Returns:
        The Response status code. 204 signifies a successful delete.

    Raises:
        MeilisearchCommunicationError: If there was an error communicating with the server.
        MeilisearchApiError: If the Meilisearch API returned an error.

    Examples
        >>> from meilisearch_python_sdk import Client
        >>> client = Client("http://localhost.com", "masterKey")
        >>> client.delete_key("abc123")
    """
    response = self._http_requests.delete(f"keys/{key}")
    return response.status_code

delete_tasks(*, uids=None, index_uids=None, statuses=None, types=None, before_enqueued_at=None, after_enqueued_at=None, before_started_at=None, after_finished_at=None)

Delete a list of tasks.

Defaults to deleting all tasks.

Parameters:

Name Type Description Default
uids list[str] | None

A list of task UIDs to delete.

None
index_uids list[str] | None

A list of index UIDs for which to delete tasks.

None
statuses list[str] | None

A list of statuses to delete.

None
types list[str] | None

A list of types to delete.

None
before_enqueued_at datetime | None

Delete tasks that were enqueued before the specified date time.

None
after_enqueued_at datetime | None

Delete tasks that were enqueued after the specified date time.

None
before_started_at datetime | None

Delete tasks that were started before the specified date time.

None
after_finished_at datetime | None

Delete tasks that were finished after the specified date time.

None

Returns:

Type Description
TaskInfo

The details of the task

Raises:

Type Description
MeilisearchCommunicationError

If there was an error communicating with the server.

MeilisearchApiError

If the Meilisearch API returned an error.

MeilisearchTimeoutError

If the connection times out.

Examples >>> from meilisearch_python_sdk import Client >>> >>> client = Client("http://localhost.com", "masterKey") >>> client.delete_tasks(client, uids=[1, 2])

Source code in meilisearch_python_sdk/_client.py
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
def delete_tasks(
    self,
    *,
    uids: list[str] | None = None,
    index_uids: list[str] | None = None,
    statuses: list[str] | None = None,
    types: list[str] | None = None,
    before_enqueued_at: datetime | None = None,
    after_enqueued_at: datetime | None = None,
    before_started_at: datetime | None = None,
    after_finished_at: datetime | None = None,
) -> TaskInfo:
    """Delete a list of tasks.

    Defaults to deleting all tasks.

    Args:
        uids: A list of task UIDs to delete.
        index_uids: A list of index UIDs for which to delete tasks.
        statuses: A list of statuses to delete.
        types: A list of types to delete.
        before_enqueued_at: Delete tasks that were enqueued before the specified date time.
        after_enqueued_at: Delete tasks that were enqueued after the specified date time.
        before_started_at: Delete tasks that were started before the specified date time.
        after_finished_at: Delete tasks that were finished after the specified date time.

    Returns:
        The details of the task

    Raises:
        MeilisearchCommunicationError: If there was an error communicating with the server.
        MeilisearchApiError: If the Meilisearch API returned an error.
        MeilisearchTimeoutError: If the connection times out.

    Examples
        >>> from meilisearch_python_sdk import Client
        >>>
        >>> client = Client("http://localhost.com", "masterKey")
        >>> client.delete_tasks(client, uids=[1, 2])
    """
    return _task.delete_tasks(
        self.http_client,
        uids=uids,
        index_uids=index_uids,
        statuses=statuses,
        types=types,
        before_enqueued_at=before_enqueued_at,
        after_enqueued_at=after_enqueued_at,
        before_started_at=before_started_at,
        after_finished_at=after_finished_at,
    )

get_all_stats()

Get stats for all indexes.

Returns:

Name Type Description
ClientStats

Information about database size and all indexes.

https ClientStats

//docs.meilisearch.com/reference/api/stats.html

Raises:

Type Description
MeilisearchCommunicationError

If there was an error communicating with the server.

MeilisearchApiError

If the Meilisearch API returned an error.

Examples >>> from meilisearch_python_sdk import Client >>> client = Client("http://localhost.com", "masterKey") >>> stats = client.get_all_stats()

Source code in meilisearch_python_sdk/_client.py
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
def get_all_stats(self) -> ClientStats:
    """Get stats for all indexes.

    Returns:
        Information about database size and all indexes.
        https://docs.meilisearch.com/reference/api/stats.html

    Raises:
        MeilisearchCommunicationError: If there was an error communicating with the server.
        MeilisearchApiError: If the Meilisearch API returned an error.

    Examples
        >>> from meilisearch_python_sdk import Client
        >>> client = Client("http://localhost.com", "masterKey")
        >>> stats = client.get_all_stats()
    """
    response = self._http_requests.get("stats")

    return ClientStats(**response.json())

get_index(uid)

Gets a single index based on the uid of the index.

Parameters:

Name Type Description Default
uid str

The index's unique identifier.

required

Returns:

Type Description
Index

An Index instance containing the information of the fetched index.

Raises:

Type Description
MeilisearchCommunicationError

If there was an error communicating with the server.

MeilisearchApiError

If the Meilisearch API returned an error.

Examples >>> from meilisearch_python_sdk import Client >>> client = Client("http://localhost.com", "masterKey") >>> index = client.get_index()

Source code in meilisearch_python_sdk/_client.py
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
def get_index(self, uid: str) -> Index:
    """Gets a single index based on the uid of the index.

    Args:
        uid: The index's unique identifier.

    Returns:
        An Index instance containing the information of the fetched index.

    Raises:
        MeilisearchCommunicationError: If there was an error communicating with the server.
        MeilisearchApiError: If the Meilisearch API returned an error.

    Examples
        >>> from meilisearch_python_sdk import Client
        >>> client = Client("http://localhost.com", "masterKey")
        >>> index = client.get_index()
    """
    return Index(self.http_client, uid, json_handler=self.json_handler).fetch_info()

get_indexes(*, offset=None, limit=None)

Get all indexes. Args: offset: Number of indexes to skip. The default of None will use the Meilisearch default. limit: Number of indexes to return. The default of None will use the Meilisearch default.

Returns:

Type Description
list[Index] | None

A list of all indexes.

Raises:

Type Description
MeilisearchCommunicationError

If there was an error communicating with the server.

MeilisearchApiError

If the Meilisearch API returned an error.

Examples >>> from meilisearch_python_sdk import Client >>> client = Client("http://localhost.com", "masterKey") as client: >>> indexes = client.get_indexes()

Source code in meilisearch_python_sdk/_client.py
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
def get_indexes(
    self, *, offset: int | None = None, limit: int | None = None
) -> list[Index] | None:
    """Get all indexes.
    Args:
        offset: Number of indexes to skip. The default of None will use the Meilisearch
            default.
        limit: Number of indexes to return. The default of None will use the Meilisearch
            default.

    Returns:
        A list of all indexes.

    Raises:
        MeilisearchCommunicationError: If there was an error communicating with the server.
        MeilisearchApiError: If the Meilisearch API returned an error.

    Examples
        >>> from meilisearch_python_sdk import Client
        >>> client = Client("http://localhost.com", "masterKey") as client:
        >>> indexes = client.get_indexes()
    """
    url = _build_offset_limit_url("indexes", offset, limit)
    response = self._http_requests.get(url)

    if not response.json()["results"]:
        return None

    return [
        Index(
            http_client=self.http_client,
            uid=x["uid"],
            primary_key=x["primaryKey"],
            created_at=x["createdAt"],
            updated_at=x["updatedAt"],
            json_handler=self.json_handler,
        )
        for x in response.json()["results"]
    ]

get_key(key)

Gets information about a specific API key.

Parameters:

Name Type Description Default
key str

The key for which to retrieve the information.

required

Returns:

Type Description
Key

The API key, or None if the key is not found.

Raises:

Type Description
MeilisearchCommunicationError

If there was an error communicating with the server.

MeilisearchApiError

If the Meilisearch API returned an error.

Examples >>> from meilisearch_python_sdk import Client >>> client = Client("http://localhost.com", "masterKey") >>> keys = client.get_key("abc123")

Source code in meilisearch_python_sdk/_client.py
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
def get_key(self, key: str) -> Key:
    """Gets information about a specific API key.

    Args:
        key: The key for which to retrieve the information.

    Returns:
        The API key, or `None` if the key is not found.

    Raises:
        MeilisearchCommunicationError: If there was an error communicating with the server.
        MeilisearchApiError: If the Meilisearch API returned an error.

    Examples
        >>> from meilisearch_python_sdk import Client
        >>> client = Client("http://localhost.com", "masterKey")
        >>> keys = client.get_key("abc123")
    """
    response = self._http_requests.get(f"keys/{key}")

    return Key(**response.json())

get_keys(*, offset=None, limit=None)

Gets the Meilisearch API keys. Args: offset: Number of indexes to skip. The default of None will use the Meilisearch default. limit: Number of indexes to return. The default of None will use the Meilisearch default.

Returns:

Type Description
KeySearch

API keys.

Raises:

Type Description
MeilisearchCommunicationError

If there was an error communicating with the server.

MeilisearchApiError

If the Meilisearch API returned an error.

Examples >>> from meilisearch_python_sdk import Client >>> client = AsyncClient("http://localhost.com", "masterKey") >>> keys = client.get_keys()

Source code in meilisearch_python_sdk/_client.py
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
def get_keys(self, *, offset: int | None = None, limit: int | None = None) -> KeySearch:
    """Gets the Meilisearch API keys.
    Args:
        offset: Number of indexes to skip. The default of None will use the Meilisearch
            default.
        limit: Number of indexes to return. The default of None will use the Meilisearch
            default.

    Returns:
        API keys.

    Raises:
        MeilisearchCommunicationError: If there was an error communicating with the server.
        MeilisearchApiError: If the Meilisearch API returned an error.

    Examples
        >>> from meilisearch_python_sdk import Client
        >>> client = AsyncClient("http://localhost.com", "masterKey")
        >>> keys = client.get_keys()
    """
    url = _build_offset_limit_url("keys", offset, limit)
    response = self._http_requests.get(url)

    return KeySearch(**response.json())

get_or_create_index(uid, primary_key=None, *, plugins=None, hits_type=JsonDict)

Get an index, or create it if it doesn't exist.

Parameters:

Name Type Description Default
uid str

The index's unique identifier.

required
primary_key str | None

The primary key of the documents. Defaults to None.

None
plugins IndexPlugins | None

Optional plugins can be provided to extend functionality.

None
hits_type Any

Allows for a custom type to be passed to use for hits. Defaults to JsonDict

JsonDict

Returns:

Type Description
Index

An instance of Index containing the information of the retrieved or newly created index.

Raises:

Type Description
MeilisearchCommunicationError

If there was an error communicating with the server.

MeilisearchApiError

If the Meilisearch API returned an error.MeilisearchTimeoutError: If the connection times out.

MeilisearchTimeoutError

If the connection times out.

Examples >>> from meilisearch_python_sdk import Client >>> client = Client("http://localhost.com", "masterKey") >>> index = client.get_or_create_index("movies")

Source code in meilisearch_python_sdk/_client.py
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
def get_or_create_index(
    self,
    uid: str,
    primary_key: str | None = None,
    *,
    plugins: IndexPlugins | None = None,
    hits_type: Any = JsonDict,
) -> Index:
    """Get an index, or create it if it doesn't exist.

    Args:
        uid: The index's unique identifier.
        primary_key: The primary key of the documents. Defaults to None.
        plugins: Optional plugins can be provided to extend functionality.
        hits_type: Allows for a custom type to be passed to use for hits. Defaults to
            JsonDict

    Returns:
        An instance of Index containing the information of the retrieved or newly created index.

    Raises:
        MeilisearchCommunicationError: If there was an error communicating with the server.
        MeilisearchApiError: If the Meilisearch API returned an error.MeilisearchTimeoutError: If the connection times out.
        MeilisearchTimeoutError: If the connection times out.

    Examples
        >>> from meilisearch_python_sdk import Client
        >>> client = Client("http://localhost.com", "masterKey")
        >>> index = client.get_or_create_index("movies")
    """
    try:
        index_instance = self.get_index(uid)
    except MeilisearchApiError as err:
        if "index_not_found" not in err.code:
            raise
        index_instance = self.create_index(
            uid, primary_key, plugins=plugins, hits_type=hits_type
        )
    return index_instance

get_raw_index(uid)

Gets the index and returns all the index information rather than an Index instance.

Parameters:

Name Type Description Default
uid str

The index's unique identifier.

required

Returns:

Type Description
IndexInfo | None

Index information rather than an Index instance.

Raises:

Type Description
MeilisearchCommunicationError

If there was an error communicating with the server.

MeilisearchApiError

If the Meilisearch API returned an error.

Examples >>> from meilisearch_python_sdk import Client >>> client = Client("http://localhost.com", "masterKey") >>> index = client.get_raw_index("movies")

Source code in meilisearch_python_sdk/_client.py
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
def get_raw_index(self, uid: str) -> IndexInfo | None:
    """Gets the index and returns all the index information rather than an Index instance.

    Args:
        uid: The index's unique identifier.

    Returns:
        Index information rather than an Index instance.

    Raises:
        MeilisearchCommunicationError: If there was an error communicating with the server.
        MeilisearchApiError: If the Meilisearch API returned an error.

    Examples
        >>> from meilisearch_python_sdk import Client
        >>> client = Client("http://localhost.com", "masterKey")
        >>> index = client.get_raw_index("movies")
    """
    response = self.http_client.get(f"indexes/{uid}")

    if response.status_code == 404:
        return None

    return IndexInfo(**response.json())

get_raw_indexes(*, offset=None, limit=None)

Gets all the indexes. Args: offset: Number of indexes to skip. The default of None will use the Meilisearch default. limit: Number of indexes to return. The default of None will use the Meilisearch default.

Returns all the index information rather than an AsyncIndex instance.

Returns:

Type Description
list[IndexInfo] | None

A list of the Index information rather than an AsyncIndex instances.

Raises:

Type Description
MeilisearchCommunicationError

If there was an error communicating with the server.

MeilisearchApiError

If the Meilisearch API returned an error.

Examples >>> from meilisearch_python_sdk import Client >>> client = Client("http://localhost.com", "masterKey") >>> index = client.get_raw_indexes()

Source code in meilisearch_python_sdk/_client.py
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
def get_raw_indexes(
    self, *, offset: int | None = None, limit: int | None = None
) -> list[IndexInfo] | None:
    """Gets all the indexes.
    Args:
        offset: Number of indexes to skip. The default of None will use the Meilisearch
            default.
        limit: Number of indexes to return. The default of None will use the Meilisearch
            default.

    Returns all the index information rather than an AsyncIndex instance.

    Returns:
        A list of the Index information rather than an AsyncIndex instances.

    Raises:
        MeilisearchCommunicationError: If there was an error communicating with the server.
        MeilisearchApiError: If the Meilisearch API returned an error.

    Examples
        >>> from meilisearch_python_sdk import Client
        >>> client = Client("http://localhost.com", "masterKey")
        >>> index = client.get_raw_indexes()
    """
    url = _build_offset_limit_url("indexes", offset, limit)
    response = self._http_requests.get(url)

    if not response.json()["results"]:
        return None

    return [IndexInfo(**x) for x in response.json()["results"]]

get_task(task_id)

Get a single task from it's task id.

Parameters:

Name Type Description Default
task_id int

Identifier of the task to retrieve.

required

Returns:

Type Description
TaskResult

Results of a task.

Raises:

Type Description
MeilisearchCommunicationError

If there was an error communicating with the server.

MeilisearchApiError

If the Meilisearch API returned an error.

MeilisearchTimeoutError

If the connection times out.

Examples >>> from meilisearch_python_sdk import Client >>> >>> client = AsyncClient("http://localhost.com", "masterKey") >>> get_task(client, 1244)

Source code in meilisearch_python_sdk/_client.py
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
def get_task(self, task_id: int) -> TaskResult:
    """Get a single task from it's task id.

    Args:
        task_id: Identifier of the task to retrieve.

    Returns:
        Results of a task.

    Raises:
        MeilisearchCommunicationError: If there was an error communicating with the server.
        MeilisearchApiError: If the Meilisearch API returned an error.
        MeilisearchTimeoutError: If the connection times out.

    Examples
        >>> from meilisearch_python_sdk import Client
        >>>
        >>> client = AsyncClient("http://localhost.com", "masterKey")
        >>> get_task(client, 1244)
    """
    return _task.get_task(self.http_client, task_id=task_id)

get_tasks(*, index_ids=None, types=None, reverse=None)

Get multiple tasks.

Parameters:

Name Type Description Default
index_ids list[str] | None

A list of index UIDs for which to get the tasks. If provided this will get the tasks only for the specified indexes, if not all tasks will be returned. Default = None

None
types str | list[str] | None

Specify specific task types to retrieve. Default = None

None
reverse bool | None

If True the tasks will be returned in reverse order. Default = None

None

Returns:

Type Description
TaskStatus

Task statuses.

Raises:

Type Description
MeilisearchCommunicationError

If there was an error communicating with the server.

MeilisearchApiError

If the Meilisearch API returned an error.

MeilisearchTimeoutError

If the connection times out.

Examples >>> from meilisearch_python_sdk import Client >>> >>> client = Client("http://localhost.com", "masterKey") >>> client.get_tasks(client)

Source code in meilisearch_python_sdk/_client.py
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
def get_tasks(
    self,
    *,
    index_ids: list[str] | None = None,
    types: str | list[str] | None = None,
    reverse: bool | None = None,
) -> TaskStatus:
    """Get multiple tasks.

    Args:
        index_ids: A list of index UIDs for which to get the tasks. If provided this will get the
            tasks only for the specified indexes, if not all tasks will be returned. Default = None
        types: Specify specific task types to retrieve. Default = None
        reverse: If True the tasks will be returned in reverse order. Default = None

    Returns:
        Task statuses.

    Raises:
        MeilisearchCommunicationError: If there was an error communicating with the server.
        MeilisearchApiError: If the Meilisearch API returned an error.
        MeilisearchTimeoutError: If the connection times out.

    Examples
        >>> from meilisearch_python_sdk import Client
        >>>
        >>> client = Client("http://localhost.com", "masterKey")
        >>> client.get_tasks(client)
    """
    return _task.get_tasks(self.http_client, index_ids=index_ids, types=types, reverse=reverse)

get_version()

Get the Meilisearch version.

Returns:

Type Description
Version

Information about the version of Meilisearch.

Raises:

Type Description
MeilisearchCommunicationError

If there was an error communicating with the server.

MeilisearchApiError

If the Meilisearch API returned an error.

Examples >>> from meilisearch_python_sdk import Client >>> client = Client("http://localhost.com", "masterKey") >>> version = client.get_version()

Source code in meilisearch_python_sdk/_client.py
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
def get_version(self) -> Version:
    """Get the Meilisearch version.

    Returns:
        Information about the version of Meilisearch.

    Raises:
        MeilisearchCommunicationError: If there was an error communicating with the server.
        MeilisearchApiError: If the Meilisearch API returned an error.

    Examples
        >>> from meilisearch_python_sdk import Client
        >>> client = Client("http://localhost.com", "masterKey")
        >>> version = client.get_version()
    """
    response = self._http_requests.get("version")

    return Version(**response.json())

health()

Get health of the Meilisearch server.

Returns:

Type Description
Health

The status of the Meilisearch server.

Raises:

Type Description
MeilisearchCommunicationError

If there was an error communicating with the server.

MeilisearchApiError

If the Meilisearch API returned an error.

Examples >>> from meilisearch_python_sdk import Client >>> client = Client("http://localhost.com", "masterKey") >>> health = client.get_health()

Source code in meilisearch_python_sdk/_client.py
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
def health(self) -> Health:
    """Get health of the Meilisearch server.

    Returns:
        The status of the Meilisearch server.

    Raises:
        MeilisearchCommunicationError: If there was an error communicating with the server.
        MeilisearchApiError: If the Meilisearch API returned an error.

    Examples
        >>> from meilisearch_python_sdk import Client
        >>> client = Client("http://localhost.com", "masterKey")
        >>> health = client.get_health()
    """
    response = self._http_requests.get("health")

    return Health(**response.json())

index(uid, *, plugins=None)

Create a local reference to an index identified by UID, without making an HTTP call.

Parameters:

Name Type Description Default
uid str

The index's unique identifier.

required
plugins IndexPlugins | None

Optional plugins can be provided to extend functionality.

None

Returns:

Type Description
Index

An Index instance.

Raises:

Type Description
MeilisearchCommunicationError

If there was an error communicating with the server.

MeilisearchApiError

If the Meilisearch API returned an error.

Examples >>> from meilisearch_python_sdk import Client >>> client = Client("http://localhost.com", "masterKey") >>> index = client.index("movies")

Source code in meilisearch_python_sdk/_client.py
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
def index(self, uid: str, *, plugins: IndexPlugins | None = None) -> Index:
    """Create a local reference to an index identified by UID, without making an HTTP call.

    Args:
        uid: The index's unique identifier.
        plugins: Optional plugins can be provided to extend functionality.

    Returns:
        An Index instance.

    Raises:
        MeilisearchCommunicationError: If there was an error communicating with the server.
        MeilisearchApiError: If the Meilisearch API returned an error.

    Examples
        >>> from meilisearch_python_sdk import Client
        >>> client = Client("http://localhost.com", "masterKey")
        >>> index = client.index("movies")
    """
    return Index(self.http_client, uid=uid, plugins=plugins, json_handler=self.json_handler)

Multi-index search.

Parameters:

Name Type Description Default
queries list[SearchParams]

List of SearchParameters

required
federation Federation | FederationMerged | None

If included a single search result with hits built from all queries will be returned. This parameter can only be used with Meilisearch >= v1.10.0. Defaults to None.

None
hits_type Any

Allows for a custom type to be passed to use for hits. Defaults to JsonDict

JsonDict

Returns:

Type Description
list[SearchResultsWithUID] | SearchResultsFederated

Results of the search

Raises:

Type Description
MeilisearchCommunicationError

If there was an error communicating with the server.

MeilisearchApiError

If the Meilisearch API returned an error.

Examples >>> from meilisearch_python_sdk import Client >>> from meilisearch_python_sdk.models.search import SearchParams >>> client = Client("http://localhost.com", "masterKey") >>> queries = [ >>> SearchParams(index_uid="my_first_index", query"Some search"), >>> SearchParams(index_uid="my_second_index", query="Another search") >>> ] >>> search_results = client.search(queries)

Source code in meilisearch_python_sdk/_client.py
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
def multi_search(
    self,
    queries: list[SearchParams],
    *,
    federation: Federation | FederationMerged | None = None,
    hits_type: Any = JsonDict,
) -> list[SearchResultsWithUID] | SearchResultsFederated:
    """Multi-index search.

    Args:
        queries: List of SearchParameters
        federation: If included a single search result with hits built from all queries will
            be returned. This parameter can only be used with Meilisearch >= v1.10.0. Defaults
            to None.
        hits_type: Allows for a custom type to be passed to use for hits. Defaults to
            JsonDict

    Returns:
        Results of the search

    Raises:
        MeilisearchCommunicationError: If there was an error communicating with the server.
        MeilisearchApiError: If the Meilisearch API returned an error.

    Examples
        >>> from meilisearch_python_sdk import Client
        >>> from meilisearch_python_sdk.models.search import SearchParams
        >>> client = Client("http://localhost.com", "masterKey")
        >>> queries = [
        >>>     SearchParams(index_uid="my_first_index", query"Some search"),
        >>>     SearchParams(index_uid="my_second_index", query="Another search")
        >>> ]
        >>> search_results = client.search(queries)
    """
    url = "multi-search"
    if federation:
        processed_queries = []
        for query in queries:
            q = query.model_dump(by_alias=True)
            del q["limit"]
            del q["offset"]
            processed_queries.append(q)
    else:
        processed_queries = [x.model_dump(by_alias=True) for x in queries]

    if federation:
        federation_payload = federation.model_dump(by_alias=True)
        if federation.facets_by_index is None:
            del federation_payload["facetsByIndex"]

    else:
        federation_payload = None

    response = self._http_requests.post(
        url,
        body={
            "federation": federation_payload,
            "queries": processed_queries,
        },
    )

    if federation:
        results = response.json()
        return SearchResultsFederated[hits_type](**results)

    return [SearchResultsWithUID[hits_type](**x) for x in response.json()["results"]]

swap_indexes(indexes)

Swap two indexes.

Parameters:

Name Type Description Default
indexes list[tuple[str, str]]

A list of tuples, each tuple should contain the indexes to swap.

required

Returns:

Type Description
TaskInfo

The details of the task.

Raises:

Type Description
MeilisearchCommunicationError

If there was an error communicating with the server.

MeilisearchApiError

If the Meilisearch API returned an error.

Examples >>> from meilisearch_python_sdk import Client >>> client = Client("http://localhost.com", "masterKey") >>> index = client.swap_indexes([("index_a", "index_b")])

Source code in meilisearch_python_sdk/_client.py
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
def swap_indexes(self, indexes: list[tuple[str, str]]) -> TaskInfo:
    """Swap two indexes.

    Args:
        indexes: A list of tuples, each tuple should contain the indexes to swap.

    Returns:
        The details of the task.

    Raises:
        MeilisearchCommunicationError: If there was an error communicating with the server.
        MeilisearchApiError: If the Meilisearch API returned an error.

    Examples
        >>> from meilisearch_python_sdk import Client
        >>> client = Client("http://localhost.com", "masterKey")
        >>> index = client.swap_indexes([("index_a", "index_b")])
    """
    processed_indexes = [{"indexes": x} for x in indexes]
    response = self._http_requests.post("swap-indexes", processed_indexes)

    return TaskInfo(**response.json())

update_key(key)

Update an API key.

Parameters:

Name Type Description Default
key KeyUpdate

The information to use in updating the key. Note that if an expires_at value is included it should be in UTC time.

required

Returns:

Type Description
Key

The updated API key.

Raises:

Type Description
MeilisearchCommunicationError

If there was an error communicating with the server.

MeilisearchApiError

If the Meilisearch API returned an error.

Examples >>> from meilisearch_python_sdk import Client >>> from meilissearch_async_client.models.client import KeyUpdate >>> client = Client("http://localhost.com", "masterKey") >>> key_info = KeyUpdate( key="abc123", >>> indexes=["*"], >>> ) >>> keys = client.update_key(key_info)

Source code in meilisearch_python_sdk/_client.py
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
def update_key(self, key: KeyUpdate) -> Key:
    """Update an API key.

    Args:
        key: The information to use in updating the key. Note that if an expires_at value
            is included it should be in UTC time.

    Returns:
        The updated API key.

    Raises:
        MeilisearchCommunicationError: If there was an error communicating with the server.
        MeilisearchApiError: If the Meilisearch API returned an error.

    Examples
        >>> from meilisearch_python_sdk import Client
        >>> from meilissearch_async_client.models.client import KeyUpdate
        >>> client = Client("http://localhost.com", "masterKey")
        >>> key_info = KeyUpdate(
                key="abc123",
        >>>     indexes=["*"],
        >>> )
        >>> keys = client.update_key(key_info)
    """
    payload = _build_update_key_payload(key, self.json_handler)
    response = self._http_requests.patch(f"keys/{key.key}", payload)

    return Key(**response.json())

wait_for_task(task_id, *, timeout_in_ms=5000, interval_in_ms=50, raise_for_status=False)

Wait until Meilisearch processes a task, and get its status.

Parameters:

Name Type Description Default
task_id int

Identifier of the task to retrieve.

required
timeout_in_ms int | None

Amount of time in milliseconds to wait before raising a MeilisearchTimeoutError. None can also be passed to wait indefinitely. Be aware that if the None option is used the wait time could be very long. Defaults to 5000.

5000
interval_in_ms int

Time interval in miliseconds to sleep between requests. Defaults to 50.

50
raise_for_status bool

When set to True a MeilisearchTaskFailedError will be raised if a task has a failed status. Defaults to False.

False

Returns:

Type Description
TaskResult

Details of the processed update status.

Raises:

Type Description
MeilisearchCommunicationError

If there was an error communicating with the server.

MeilisearchApiError

If the Meilisearch API returned an error.

MeilisearchTimeoutError

If the connection times out.

MeilisearchTaskFailedError

If raise_for_status is True and a task has a failed status.

Examples >>> from meilisearch_python_sdk import Client >>> >>> documents = [ >>> {"id": 1, "title": "Movie 1", "genre": "comedy"}, >>> {"id": 2, "title": "Movie 2", "genre": "drama"}, >>> ] >>> client = Client("http://localhost.com", "masterKey") >>> index = client.index("movies") >>> response = await index.add_documents(documents) >>> client.wait_for_task(response.update_id)

Source code in meilisearch_python_sdk/_client.py
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
def wait_for_task(
    self,
    task_id: int,
    *,
    timeout_in_ms: int | None = 5000,
    interval_in_ms: int = 50,
    raise_for_status: bool = False,
) -> TaskResult:
    """Wait until Meilisearch processes a task, and get its status.

    Args:
        task_id: Identifier of the task to retrieve.
        timeout_in_ms: Amount of time in milliseconds to wait before raising a
            MeilisearchTimeoutError. `None` can also be passed to wait indefinitely. Be aware that
            if the `None` option is used the wait time could be very long. Defaults to 5000.
        interval_in_ms: Time interval in miliseconds to sleep between requests. Defaults to 50.
        raise_for_status: When set to `True` a MeilisearchTaskFailedError will be raised if a task
            has a failed status. Defaults to False.

    Returns:
        Details of the processed update status.

    Raises:
        MeilisearchCommunicationError: If there was an error communicating with the server.
        MeilisearchApiError: If the Meilisearch API returned an error.
        MeilisearchTimeoutError: If the connection times out.
        MeilisearchTaskFailedError: If `raise_for_status` is `True` and a task has a failed status.

    Examples
        >>> from meilisearch_python_sdk import Client
        >>> >>> documents = [
        >>>     {"id": 1, "title": "Movie 1", "genre": "comedy"},
        >>>     {"id": 2, "title": "Movie 2", "genre": "drama"},
        >>> ]
        >>> client = Client("http://localhost.com", "masterKey")
        >>> index = client.index("movies")
        >>> response = await index.add_documents(documents)
        >>> client.wait_for_task(response.update_id)
    """
    return _task.wait_for_task(
        self.http_client,
        task_id=task_id,
        timeout_in_ms=timeout_in_ms,
        interval_in_ms=interval_in_ms,
        raise_for_status=raise_for_status,
    )