Feat/index stats query params

[vivek378521]

Pull Request

Related issue

Fixes #1234

What does this PR do?

Meilisearch v1.44.0 adds two optional query parameters to GET /indexes/{indexUid}/stats and GET /stats:

• showInternalDatabaseSizes — when true, index stat objects include an internalDatabaseSizes dictionary
• sizeFormat — "human" for readable sizes (e.g. "19.64 MiB") or "raw" for byte counts (default)

This PR wires those parameters through the Python SDK:

• Index.get_stats() — keyword-only show_internal_database_sizes and size_format
• Client.get_all_stats() — same parameters
• IndexStats — optional internal_database_sizes: Dict[str, Any] (loosely typed; keys may change between Meilisearch versions, per API guidance)
• SizeFormat enum (raw / human) for optional typing on size_format
• Integration tests for both endpoints (raw vs human sizes, combined params)
• .code-samples.meilisearch.yaml — updated get_index_stats_1 and get_indexes_stats_1

Query params are only sent when the caller provides them (backward compatible). Boolean values are encoded as lowercase true/false.

Example:

stats = client.index("movies").get_stats(
    show_internal_database_sizes=True,
    size_format="human",
)

PR checklist

Please check if your PR fulfills the following requirements:

• Did you use any AI tool while implementing this PR (code, tests, docs, etc.)? If yes, disclose it in the PR description and describe what it was used for. AI usage is allowed when it is disclosed.
  • Yes. Cursor (AI-assisted IDE) was used for implementation guidance, test structure, PR description drafting, and debugging (e.g. boolean query encoding). All changes were reviewed and committed by the author.
• Does this PR fix an existing issue, or have you listed the changes applied in the PR description (and why they are needed)?
• Have you read the contributing guidelines?
• Have you made sure that the title is accurate and descriptive of the changes?

Overview

Adds support for two optional query parameters introduced in Meilisearch v1.44.0 to the Python SDK's index and global stats endpoints:

• show_internal_database_sizes: When true, includes an internalDatabaseSizes dictionary showing internal database names and sizes
• size_format: Controls output format—"human" for human-readable units (e.g., "19.64 MiB") or "raw" for byte counts (default)

Changes

New Type Definition (meilisearch/models/index.py)

• Added SizeFormat enum with RAW = "raw" and HUMAN = "human" members
• Extended IndexStats model with optional internal_database_sizes: Optional[Dict[str, Any]] field to accommodate loosely-typed internal database information

API Updates

• Index.get_stats(): Added keyword-only parameters show_internal_database_sizes (Optional[bool]) and size_format (Optional[Union[SizeFormat, str]])
• Client.get_all_stats(): Added the same keyword-only parameters
• Both methods conditionally append query parameters to the request URL only when provided, maintaining backward compatibility
• Supports both SizeFormat enum values and raw string values for size_format
• Boolean parameters are encoded as lowercase "true"/"false" in query strings

Test Coverage

• tests/index/test_index_stats_meilisearch.py: Added tests validating:
  • internal_database_sizes presence and content when show_internal_database_sizes=True
  • Human-readable size formatting when size_format=SizeFormat.HUMAN is combined with internal database sizes
  • String form of size format parameter
• tests/client/test_client_stats_meilisearch.py: Added tests for global stats with similar coverage for internal database sizes and human-readable formatting
• Tests use a regex HUMAN_SIZE_PATTERN to validate human-readable size strings

Documentation

• Updated .code-samples.meilisearch.yaml: Examples for get_index_stats_1 and get_indexes_stats_1 now demonstrate both parameters with show_internal_database_sizes=True and size_format='human'

Technical Notes

• Query parameters are only sent when explicitly provided, preserving backward compatibility with existing code
• Internal database size keys are intentionally not strongly typed due to API instability

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: b8a81cf1-7e3f-483d-a003-bec8d62cd0ec

📥 Commits

Reviewing files that changed from the base of the PR and between f2b7d58 and 701755a.

📒 Files selected for processing (1)

• tests/client/test_client_stats_meilisearch.py

🚧 Files skipped from review as they are similar to previous changes (1)

• tests/client/test_client_stats_meilisearch.py

---

📝 Walkthrough

Walkthrough

This PR extends the Meilisearch Python SDK's stats APIs: Client.get_all_stats() and Index.get_stats() now accept optional show_internal_database_sizes and size_format parameters, adds a SizeFormat enum and an internal_database_sizes field to IndexStats, updates docs samples, and adds tests for the new behavior.

Changes

Stats API Query Parameters Extension

Layer / File(s)	Summary
Data Model & SizeFormat Enum meilisearch/models/index.py	Introduces SizeFormat enum with RAW and HUMAN values, and extends IndexStats with optional internal_database_sizes field to hold database-level size breakdowns.
Client.get_all_stats() API Extension meilisearch/client.py	Imports SizeFormat and updates get_all_stats() to accept optional keyword-only parameters show_internal_database_sizes and size_format (enum or string), building and appending them as query parameters to the stats endpoint request.
Index.get_stats() API Extension meilisearch/index.py	Imports SizeFormat and updates get_stats() to accept optional keyword-only parameters show_internal_database_sizes and size_format (enum or string), with identical query parameter construction logic mirroring the client method.
Index API Test Coverage tests/index/test_index_stats_meilisearch.py	Adds HUMAN_SIZE_PATTERN regex and three new tests validating get_stats() with internal database sizes, human-readable format via SizeFormat.HUMAN, and mixed string format parameter modes.
Client API Test Coverage tests/client/test_client_stats_meilisearch.py	Adds HUMAN_SIZE_PATTERN regex and three new tests validating get_all_stats() with internal database sizes, human-readable format via SizeFormat.HUMAN, and mixed string format parameter modes.
Documentation Code Samples .code-samples.meilisearch.yaml	Updates get_index_stats_1 and get_indexes_stats_1 examples to demonstrate calling the stats methods with show_internal_database_sizes=True and size_format='human' parameters.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related issues

• [Meilisearch v1.44.0] Add human-formatted sizes and detailed DB sizes in stats meilisearch-rust#789: Implements the same stats query parameters (showInternalDatabaseSizes, sizeFormat) in the Rust SDK — directly related implementation.
• [Meilisearch v1.44.0] Add human-formatted sizes and detailed DB sizes in stats meilisearch-swift#521: Adds support for the same stats parameters in the Swift SDK — matching API-level change.
• [Meilisearch v1.44.0] Add human-formatted sizes and detailed DB sizes in stats meilisearch-java#966: Extends the Java SDK with identical stats parameter handling and tests — related objective.
• [Meilisearch v1.44.0] Add human-formatted sizes and detailed DB sizes in stats meilisearch-dart#488: Implements SizeFormat enum and stats parameter support in the Dart SDK — same feature alignment.

Poem

🐰 I hopped through stats to find each size,

human-readable numbers and tiny surprise,
RAW or HUMAN, the choice now is near,
internal DB sizes for each index appear,
cheers — the stats are clearer this year!

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'Feat/index stats query params' is concise and directly describes the main feature added—query parameters for index stats endpoints.
Linked Issues check	✅ Passed	The PR fully implements all coding requirements from issue #1234: both Index.get_stats() and Client.get_all_stats() accept show_internal_database_sizes and size_format parameters; IndexStats includes internal_database_sizes field; SizeFormat enum is defined; comprehensive tests cover raw/human sizes and combined parameters; and code samples are updated.
Out of Scope Changes check	✅ Passed	All changes are within scope—method signatures, model updates, enum definitions, tests, and documentation samples all directly support the objective of exposing the two new Meilisearch v1.44.0 query parameters.
Docstring Coverage	✅ Passed	Docstring coverage is 93.33% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

🧹 Nitpick comments (1)

tests/client/test_client_stats_meilisearch.py (1)

39-54: ⚡ Quick win

The internal-sizes human-format check can silently no-op.

Unlike test_get_all_stats_with_internal_database_sizes, this test has no any(...) guard asserting that at least one index actually contains internalDatabaseSizes. If no index returns the key, the loop body never runs and the human-format assertion on internal sizes is skipped (only the top-level databaseSize check on Line 48 would cover the format). Add a presence guard to ensure the internal-size branch is exercised.

✅ Proposed guard

     assert isinstance(response["databaseSize"], str)
     assert HUMAN_SIZE_PATTERN.match(response["databaseSize"])
+    assert any(
+        "internalDatabaseSizes" in index_stats for index_stats in response["indexes"].values()
+    )
     for index_stats in response["indexes"].values():
         if "internalDatabaseSizes" in index_stats:

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@tests/client/test_client_stats_meilisearch.py` around lines 39 - 54, The test
test_get_all_stats_with_size_format can silently skip the internalDatabaseSizes
checks if no index contains that key; update the test to assert the branch is
exercised by collecting presence from response (e.g., use any(...) on
response["indexes"].values() to check for "internalDatabaseSizes") and assert
that at least one index contains internalDatabaseSizes before running the loop
that validates HUMAN_SIZE_PATTERN on those values; operate on the existing
response variable and keep the databaseSize string checks, then add the presence
guard to fail the test if no internal sizes are present.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@tests/client/test_client_stats_meilisearch.py`:
- Around line 39-54: The test test_get_all_stats_with_size_format can silently
skip the internalDatabaseSizes checks if no index contains that key; update the
test to assert the branch is exercised by collecting presence from response
(e.g., use any(...) on response["indexes"].values() to check for
"internalDatabaseSizes") and assert that at least one index contains
internalDatabaseSizes before running the loop that validates HUMAN_SIZE_PATTERN
on those values; operate on the existing response variable and keep the
databaseSize string checks, then add the presence guard to fail the test if no
internal sizes are present.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: e585e2a7-2f74-4d44-95cb-53d88495ad07

📥 Commits

Reviewing files that changed from the base of the PR and between ada25db and f2b7d58.

📒 Files selected for processing (6)

• .code-samples.meilisearch.yaml
• meilisearch/client.py
• meilisearch/index.py
• meilisearch/models/index.py
• tests/client/test_client_stats_meilisearch.py
• tests/index/test_index_stats_meilisearch.py