matrixone-python-sdk 0.1.4__tar.gz → 0.1.5__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (76) hide show
  1. {matrixone_python_sdk-0.1.4 → matrixone_python_sdk-0.1.5}/MANIFEST.in +3 -0
  2. {matrixone_python_sdk-0.1.4/matrixone_python_sdk.egg-info → matrixone_python_sdk-0.1.5}/PKG-INFO +347 -6
  3. {matrixone_python_sdk-0.1.4 → matrixone_python_sdk-0.1.5}/README.md +344 -4
  4. {matrixone_python_sdk-0.1.4 → matrixone_python_sdk-0.1.5}/README_USER.md +344 -4
  5. {matrixone_python_sdk-0.1.4 → matrixone_python_sdk-0.1.5}/matrixone/async_client.py +27 -11
  6. matrixone_python_sdk-0.1.5/matrixone/cli_tools.py +1895 -0
  7. {matrixone_python_sdk-0.1.4 → matrixone_python_sdk-0.1.5}/matrixone/client.py +126 -12
  8. {matrixone_python_sdk-0.1.4 → matrixone_python_sdk-0.1.5}/matrixone/connection_hooks.py +54 -5
  9. {matrixone_python_sdk-0.1.4 → matrixone_python_sdk-0.1.5}/matrixone/index_utils.py +4 -2
  10. {matrixone_python_sdk-0.1.4 → matrixone_python_sdk-0.1.5/matrixone_python_sdk.egg-info}/PKG-INFO +347 -6
  11. {matrixone_python_sdk-0.1.4 → matrixone_python_sdk-0.1.5}/matrixone_python_sdk.egg-info/SOURCES.txt +2 -0
  12. {matrixone_python_sdk-0.1.4 → matrixone_python_sdk-0.1.5}/matrixone_python_sdk.egg-info/entry_points.txt +1 -1
  13. {matrixone_python_sdk-0.1.4 → matrixone_python_sdk-0.1.5}/matrixone_python_sdk.egg-info/requires.txt +1 -0
  14. matrixone_python_sdk-0.1.5/mo_diag.py +120 -0
  15. {matrixone_python_sdk-0.1.4 → matrixone_python_sdk-0.1.5}/pyproject.toml +4 -3
  16. {matrixone_python_sdk-0.1.4 → matrixone_python_sdk-0.1.5}/requirements.txt +3 -0
  17. {matrixone_python_sdk-0.1.4 → matrixone_python_sdk-0.1.5}/setup.py +4 -1
  18. {matrixone_python_sdk-0.1.4 → matrixone_python_sdk-0.1.5}/LICENSE +0 -0
  19. {matrixone_python_sdk-0.1.4 → matrixone_python_sdk-0.1.5}/examples/example_01_basic_connection.py +0 -0
  20. {matrixone_python_sdk-0.1.4 → matrixone_python_sdk-0.1.5}/examples/example_02_account_management.py +0 -0
  21. {matrixone_python_sdk-0.1.4 → matrixone_python_sdk-0.1.5}/examples/example_03_async_operations.py +0 -0
  22. {matrixone_python_sdk-0.1.4 → matrixone_python_sdk-0.1.5}/examples/example_04_transaction_management.py +0 -0
  23. {matrixone_python_sdk-0.1.4 → matrixone_python_sdk-0.1.5}/examples/example_05_snapshot_restore.py +0 -0
  24. {matrixone_python_sdk-0.1.4 → matrixone_python_sdk-0.1.5}/examples/example_06_sqlalchemy_integration.py +0 -0
  25. {matrixone_python_sdk-0.1.4 → matrixone_python_sdk-0.1.5}/examples/example_07_advanced_features.py +0 -0
  26. {matrixone_python_sdk-0.1.4 → matrixone_python_sdk-0.1.5}/examples/example_08_pubsub_operations.py +0 -0
  27. {matrixone_python_sdk-0.1.4 → matrixone_python_sdk-0.1.5}/examples/example_09_logger_integration.py +0 -0
  28. {matrixone_python_sdk-0.1.4 → matrixone_python_sdk-0.1.5}/examples/example_10_version_management.py +0 -0
  29. {matrixone_python_sdk-0.1.4 → matrixone_python_sdk-0.1.5}/examples/example_11_matrixone_version_demo.py +0 -0
  30. {matrixone_python_sdk-0.1.4 → matrixone_python_sdk-0.1.5}/examples/example_12_vector_basics.py +0 -0
  31. {matrixone_python_sdk-0.1.4 → matrixone_python_sdk-0.1.5}/examples/example_13_vector_indexes.py +0 -0
  32. {matrixone_python_sdk-0.1.4 → matrixone_python_sdk-0.1.5}/examples/example_14_vector_search.py +0 -0
  33. {matrixone_python_sdk-0.1.4 → matrixone_python_sdk-0.1.5}/examples/example_15_vector_advanced.py +0 -0
  34. {matrixone_python_sdk-0.1.4 → matrixone_python_sdk-0.1.5}/examples/example_18_snapshot_orm.py +0 -0
  35. {matrixone_python_sdk-0.1.4 → matrixone_python_sdk-0.1.5}/examples/example_19_sqlalchemy_style_orm.py +0 -0
  36. {matrixone_python_sdk-0.1.4 → matrixone_python_sdk-0.1.5}/examples/example_20_sqlalchemy_engine_integration.py +0 -0
  37. {matrixone_python_sdk-0.1.4 → matrixone_python_sdk-0.1.5}/examples/example_21_advanced_orm_features.py +0 -0
  38. {matrixone_python_sdk-0.1.4 → matrixone_python_sdk-0.1.5}/examples/example_22_unified_sql_builder.py +0 -0
  39. {matrixone_python_sdk-0.1.4 → matrixone_python_sdk-0.1.5}/examples/example_24_query_update.py +0 -0
  40. {matrixone_python_sdk-0.1.4 → matrixone_python_sdk-0.1.5}/examples/example_25_metadata_operations.py +0 -0
  41. {matrixone_python_sdk-0.1.4 → matrixone_python_sdk-0.1.5}/examples/example_connection_hooks.py +0 -0
  42. {matrixone_python_sdk-0.1.4 → matrixone_python_sdk-0.1.5}/examples/example_dynamic_logging.py +0 -0
  43. {matrixone_python_sdk-0.1.4 → matrixone_python_sdk-0.1.5}/examples/example_ivf_stats_complete.py +0 -0
  44. {matrixone_python_sdk-0.1.4 → matrixone_python_sdk-0.1.5}/matrixone/__init__.py +0 -0
  45. {matrixone_python_sdk-0.1.4 → matrixone_python_sdk-0.1.5}/matrixone/account.py +0 -0
  46. {matrixone_python_sdk-0.1.4 → matrixone_python_sdk-0.1.5}/matrixone/async_metadata_manager.py +0 -0
  47. {matrixone_python_sdk-0.1.4 → matrixone_python_sdk-0.1.5}/matrixone/async_orm.py +0 -0
  48. {matrixone_python_sdk-0.1.4 → matrixone_python_sdk-0.1.5}/matrixone/async_vector_index_manager.py +0 -0
  49. {matrixone_python_sdk-0.1.4 → matrixone_python_sdk-0.1.5}/matrixone/base_client.py +0 -0
  50. {matrixone_python_sdk-0.1.4 → matrixone_python_sdk-0.1.5}/matrixone/config.py +0 -0
  51. {matrixone_python_sdk-0.1.4 → matrixone_python_sdk-0.1.5}/matrixone/exceptions.py +0 -0
  52. {matrixone_python_sdk-0.1.4 → matrixone_python_sdk-0.1.5}/matrixone/logger.py +0 -0
  53. {matrixone_python_sdk-0.1.4 → matrixone_python_sdk-0.1.5}/matrixone/metadata.py +0 -0
  54. {matrixone_python_sdk-0.1.4 → matrixone_python_sdk-0.1.5}/matrixone/moctl.py +0 -0
  55. {matrixone_python_sdk-0.1.4 → matrixone_python_sdk-0.1.5}/matrixone/orm.py +0 -0
  56. {matrixone_python_sdk-0.1.4 → matrixone_python_sdk-0.1.5}/matrixone/pitr.py +0 -0
  57. {matrixone_python_sdk-0.1.4 → matrixone_python_sdk-0.1.5}/matrixone/pubsub.py +0 -0
  58. {matrixone_python_sdk-0.1.4 → matrixone_python_sdk-0.1.5}/matrixone/restore.py +0 -0
  59. {matrixone_python_sdk-0.1.4 → matrixone_python_sdk-0.1.5}/matrixone/search_vector_index.py +0 -0
  60. {matrixone_python_sdk-0.1.4 → matrixone_python_sdk-0.1.5}/matrixone/snapshot.py +0 -0
  61. {matrixone_python_sdk-0.1.4 → matrixone_python_sdk-0.1.5}/matrixone/sql_builder.py +0 -0
  62. {matrixone_python_sdk-0.1.4 → matrixone_python_sdk-0.1.5}/matrixone/sqlalchemy_ext/__init__.py +0 -0
  63. {matrixone_python_sdk-0.1.4 → matrixone_python_sdk-0.1.5}/matrixone/sqlalchemy_ext/adapters.py +0 -0
  64. {matrixone_python_sdk-0.1.4 → matrixone_python_sdk-0.1.5}/matrixone/sqlalchemy_ext/dialect.py +0 -0
  65. {matrixone_python_sdk-0.1.4 → matrixone_python_sdk-0.1.5}/matrixone/sqlalchemy_ext/fulltext_index.py +0 -0
  66. {matrixone_python_sdk-0.1.4 → matrixone_python_sdk-0.1.5}/matrixone/sqlalchemy_ext/fulltext_search.py +0 -0
  67. {matrixone_python_sdk-0.1.4 → matrixone_python_sdk-0.1.5}/matrixone/sqlalchemy_ext/hnsw_config.py +0 -0
  68. {matrixone_python_sdk-0.1.4 → matrixone_python_sdk-0.1.5}/matrixone/sqlalchemy_ext/ivf_config.py +0 -0
  69. {matrixone_python_sdk-0.1.4 → matrixone_python_sdk-0.1.5}/matrixone/sqlalchemy_ext/table_builder.py +0 -0
  70. {matrixone_python_sdk-0.1.4 → matrixone_python_sdk-0.1.5}/matrixone/sqlalchemy_ext/vector_index.py +0 -0
  71. {matrixone_python_sdk-0.1.4 → matrixone_python_sdk-0.1.5}/matrixone/sqlalchemy_ext/vector_type.py +0 -0
  72. {matrixone_python_sdk-0.1.4 → matrixone_python_sdk-0.1.5}/matrixone/version.py +0 -0
  73. {matrixone_python_sdk-0.1.4 → matrixone_python_sdk-0.1.5}/matrixone_python_sdk.egg-info/dependency_links.txt +0 -0
  74. {matrixone_python_sdk-0.1.4 → matrixone_python_sdk-0.1.5}/matrixone_python_sdk.egg-info/not-zip-safe +0 -0
  75. {matrixone_python_sdk-0.1.4 → matrixone_python_sdk-0.1.5}/matrixone_python_sdk.egg-info/top_level.txt +0 -0
  76. {matrixone_python_sdk-0.1.4 → matrixone_python_sdk-0.1.5}/setup.cfg +0 -0
@@ -7,6 +7,9 @@ include LICENSE
7
7
  # Include requirements
8
8
  include requirements.txt
9
9
 
10
+ # Include mo_diag script
11
+ include mo_diag.py
12
+
10
13
  # Include examples (recommended for user experience)
11
14
  recursive-include examples *.py
12
15
 
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: matrixone-python-sdk
3
- Version: 0.1.4
3
+ Version: 0.1.5
4
4
  Summary: A comprehensive Python SDK for MatrixOne database operations with vector search, fulltext search, and advanced features
5
5
  Home-page: https://github.com/matrixorigin/matrixone
6
6
  Author: MatrixOne Team
@@ -12,7 +12,7 @@ Project-URL: Documentation, https://matrixone.readthedocs.io/
12
12
  Project-URL: Repository, https://github.com/matrixorigin/matrixone
13
13
  Project-URL: Issues, https://github.com/matrixorigin/matrixone/issues
14
14
  Project-URL: Changelog, https://github.com/matrixorigin/matrixone/blob/main/clients/python/CHANGELOG.md
15
- Keywords: matrixone,database,vector,search,sqlalchemy,python
15
+ Keywords: matrixone,database,vector,search,sqlalchemy,python,diagnostic,cli,monitoring,ivf,hnsw
16
16
  Classifier: Development Status :: 4 - Beta
17
17
  Classifier: Intended Audience :: Developers
18
18
  Classifier: License :: OSI Approved :: Apache Software License
@@ -34,6 +34,7 @@ Requires-Dist: SQLAlchemy<3.0.0,>=1.4.0
34
34
  Requires-Dist: typing-extensions>=4.0.0
35
35
  Requires-Dist: python-dateutil>=2.8.0
36
36
  Requires-Dist: numpy>=1.20.0
37
+ Requires-Dist: prompt_toolkit>=3.0.0
37
38
  Provides-Extra: dev
38
39
  Requires-Dist: pytest>=6.0; extra == "dev"
39
40
  Requires-Dist: pytest-asyncio>=0.18.0; extra == "dev"
@@ -107,6 +108,13 @@ A comprehensive, high-level Python SDK for MatrixOne that provides SQLAlchemy-li
107
108
  - 🔧 **Version Management**: Automatic backend version detection and compatibility
108
109
  - 🛡️ **Type Safety**: Full type hints support with comprehensive documentation
109
110
  - 📚 **SQLAlchemy Integration**: Seamless SQLAlchemy ORM integration with enhanced features
111
+ - 🛠️ **mo-diag CLI Tool**: Interactive diagnostic tool for MatrixOne database maintenance
112
+ - Index health monitoring and verification
113
+ - IVF/HNSW vector index status inspection
114
+ - Table statistics and metadata analysis
115
+ - Interactive shell with Tab completion and command history
116
+ - Non-interactive mode for scripting and automation
117
+ - Batch operations on tables and indexes
110
118
 
111
119
  ## 🚀 Installation
112
120
 
@@ -279,12 +287,336 @@ else:
279
287
  print(f"Running release version: {client.get_backend_version()}")
280
288
  ```
281
289
 
282
- ## Advanced Features
290
+ ## 🛠️ mo-diag - Interactive Diagnostic Tool
283
291
 
284
- ### PITR (Point-in-Time Recovery)
292
+ The `mo-diag` command-line tool provides an interactive shell for diagnosing and maintaining MatrixOne databases, with a special focus on vector indexes, secondary indexes, and table statistics.
293
+
294
+ ### Installation
295
+
296
+ After installing the SDK, `mo-diag` is automatically available as a command:
297
+
298
+ ```bash
299
+ pip install matrixone-python-sdk
300
+ mo-diag --help
301
+ ```
302
+
303
+ ### Quick Start
304
+
305
+ #### Interactive Mode
306
+
307
+ Launch the interactive shell to execute multiple diagnostic commands:
308
+
309
+ ```bash
310
+ # Connect to default localhost
311
+ mo-diag --database test
312
+
313
+ # Connect to remote database
314
+ mo-diag --host 192.168.1.100 --port 6001 --user admin --password secret --database production
315
+ ```
316
+
317
+ **Interactive Features**:
318
+ - 🔍 **Tab Completion**: Press `Tab` to auto-complete commands, table names, and database names
319
+ - ⬆️⬇️ **Command History**: Use arrow keys to browse command history
320
+ - 🔎 **History Search**: Press `Ctrl+R` to search command history
321
+ - 🎨 **Colored Output**: Clear visual feedback with syntax highlighting
322
+ - 💾 **Persistent History**: Command history saved to `~/.mo_diag_history`
323
+
324
+ #### Non-Interactive Mode
325
+
326
+ Execute single commands directly for scripting and automation:
327
+
328
+ ```bash
329
+ # Check IVF index status
330
+ mo-diag -d test -c "show_ivf_status"
331
+
332
+ # Get detailed table statistics
333
+ mo-diag -d test -c "show_table_stats my_table -a -d"
334
+
335
+ # Execute SQL query
336
+ mo-diag -d test -c "sql SELECT COUNT(*) FROM my_table"
337
+
338
+ # Flush table and all indexes
339
+ mo-diag -d test -c "flush_table my_table"
340
+ ```
341
+
342
+ ### Available Commands
343
+
344
+ #### Index Management
345
+
346
+ **`show_indexes <table> [database]`**
347
+ - Display all indexes for a table including IVF, HNSW, Fulltext, and regular indexes
348
+ - Shows physical table names, index types, and statistics
349
+ - Includes object counts, row counts, and sizes for vector/fulltext indexes
350
+
351
+ ```
352
+ MO-DIAG[test]> show_indexes ivf_health_demo_docs
353
+
354
+ 📊 Secondary Indexes for 'test.ivf_health_demo_docs'
355
+
356
+ *************************** 1. row ***************************
357
+ Index Name: idx_embedding_ivf_v2
358
+ Algorithm: ivfflat
359
+ Table Type: metadata
360
+ Physical Table: __mo_index_secondary_0199e725-0a7a-77b8-b689-ccdd0a33f581
361
+ Columns: embedding
362
+ Statistics:
363
+ - Objects: 1
364
+ - Rows: 7
365
+ - Compressed Size: 940 B
366
+ - Original Size: 1.98 KB
367
+
368
+ *************************** 2. row ***************************
369
+ Index Name: idx_embedding_ivf_v2
370
+ Algorithm: ivfflat
371
+ Table Type: centroids
372
+ Physical Table: __mo_index_secondary_0199e725-0a7b-706e-8f0a-a50edc3621a1
373
+ Columns: embedding
374
+ Statistics:
375
+ - Objects: 1
376
+ - Rows: 17
377
+ - Compressed Size: 3.09 KB
378
+ - Original Size: 6.83 KB
379
+ ```
380
+
381
+ **`show_all_indexes [database]`**
382
+ - Health report for all tables with secondary indexes in the database
383
+ - Row count consistency checks
384
+ - IVF/HNSW/Fulltext index status
385
+
386
+ ```
387
+ MO-DIAG[test]> show_all_indexes
388
+
389
+ 📊 Index Health Report for Database 'test':
390
+ ═══════════════════════════════════════════════════════════════════════════
391
+
392
+ 🟢 HEALTHY TABLES (1):
393
+ ─────────────────────────────────────────────────────────────────────────
394
+ Table Name | Indexes | Row Count | Notes
395
+ ──────────────────────────────────────────────────────────────────────────
396
+ ivf_health_demo_docs | 1 | ✓ 1000 rows | IVF: 17 centroids, 1000 vectors
397
+ ```
398
+
399
+ **`verify_counts <table> [database]`**
400
+ - Verify row count consistency between main table and all its secondary indexes
401
+ - Highlights any mismatches
402
+
403
+ ```
404
+ MO-DIAG[test]> verify_counts my_table
405
+
406
+ 📊 Row Count Verification for 'test.my_table'
407
+ ════════════════════════════════════════════════════════════════════════════
408
+ Main table: 10,000 rows
409
+ ────────────────────────────────────────────────────────────────────────────
410
+ ✓ __mo_index_secondary_xxx: 10,000 rows
411
+ ✓ __mo_index_unique_yyy: 10,000 rows
412
+ ════════════════════════════════════════════════════════════════════════════
413
+ ✅ PASSED: All index tables match (10,000 rows)
414
+ ```
415
+
416
+ #### Vector Index Monitoring
417
+
418
+ **`show_ivf_status [database] [-v] [-t table]`**
419
+ - Display IVF index building status and centroid distribution
420
+ - `-v`: Verbose mode with detailed centroid information
421
+ - `-t <table>`: Filter by specific table
422
+
423
+ ```
424
+ MO-DIAG[test]> show_ivf_status
425
+
426
+ 📊 IVF Index Status in 'test':
427
+ ════════════════════════════════════════════════════════════════════════════
428
+ Table | Index | Column | Centroids | Vectors | Balance | Status
429
+ ────────────────────────────────────────────────────────────────────────────
430
+ ivf_health_demo_docs | idx_embedding_ivf_v2 | embedding | 17 | 1,000 | 2.35 | ✓ active
431
+ ```
432
+
433
+ #### Table Statistics
434
+
435
+ **`show_table_stats <table> [database] [-t] [-a] [-d]`**
436
+ - Display table metadata and statistics
437
+ - `-t`: Include tombstone statistics
438
+ - `-a`: Include all indexes (hierarchical view with -d)
439
+ - `-d`: Show detailed object lists
440
+
441
+ ```
442
+ MO-DIAG[test]> show_table_stats ivf_health_demo_docs -a -d
443
+
444
+ Table: ivf_health_demo_docs
445
+ Objects: 1 | Rows: 1,000 | Null: 0 | Original: 176.03 KB | Compressed: 156.24 KB
446
+
447
+ Objects:
448
+ Object Name | Rows | Null Cnt | Original Size | Compressed Size
449
+ ─────────────────────────────────────────────────────────────────────────────────────────────────────
450
+ 0199e729-642e-71e0-b338-67c4980ee294_00000 | 1000 | 0 | 176.03 KB | 156.24 KB
451
+
452
+ Index: idx_embedding_ivf_v2
453
+ └─ Physical Table (metadata): __mo_index_secondary_0199e725-0a7a-77b8-b689-ccdd0a33f581
454
+ Objects: 1 | Rows: 7 | Null: 0 | Original: 1.98 KB | Compressed: 940 B
455
+
456
+ Objects:
457
+ Object Name | Rows | Null Cnt | Original Size | Compressed Size
458
+ ─────────────────────────────────────────────────────────────────────────────────────────────────────
459
+ 0199e729-642a-7d36-ac37-0ae17325f7ec_00000 | 7 | 0 | 1.98 KB | 940 B
460
+ ```
461
+
462
+ #### Database Operations
463
+
464
+ **`flush_table <table> [database]`**
465
+ - Flush main table and all its secondary index physical tables
466
+ - Includes IVF metadata/centroids/entries, HNSW, Fulltext, and regular indexes
467
+ - Requires sys user privileges
468
+
469
+ ```
470
+ MO-DIAG[test]> flush_table ivf_health_demo_docs
471
+
472
+ 🔄 Flushing table: test.ivf_health_demo_docs
473
+ ✓ Main table flushed: ivf_health_demo_docs
474
+ 📋 Found 3 index physical tables
475
+
476
+ Index: idx_embedding_ivf_v2
477
+ ✓ metadata: __mo_index_secondary_xxx
478
+ ✓ centroids: __mo_index_secondary_yyy
479
+ ✓ entries: __mo_index_secondary_zzz
480
+
481
+ 📊 Summary:
482
+ Main table: ✓ flushed
483
+ Index tables: 3/3 flushed successfully
484
+ ```
485
+
486
+ **`tables [database]`**
487
+ - List all tables in current or specified database
488
+
489
+ **`databases`**
490
+ - List all databases (highlights current database)
491
+
492
+ **`use <database>`**
493
+ - Switch to a different database
494
+
495
+ **`sql <SQL statement>`**
496
+ - Execute arbitrary SQL query
497
+
498
+ ```
499
+ MO-DIAG[test]> sql SELECT COUNT(*) FROM my_table
500
+
501
+ col0
502
+ ----
503
+ 10000
504
+
505
+ 1 row(s) returned
506
+ ```
507
+
508
+ #### Utility Commands
509
+
510
+ **`history [n | -c]`**
511
+ - Show last n commands (default: 20)
512
+ - `-c`: Clear command history
513
+
514
+ **`help [command]`**
515
+ - Show help for all commands or specific command
516
+
517
+ **`exit` / `quit`**
518
+ - Exit the interactive shell
519
+
520
+ ### Command-Line Options
521
+
522
+ ```
523
+ usage: mo-diag [-h] [--host HOST] [--port PORT] [--user USER]
524
+ [--password PASSWORD] [--database DATABASE]
525
+ [--log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}]
526
+ [--command COMMAND]
527
+
528
+ options:
529
+ --host HOST Database host (default: localhost)
530
+ --port PORT Database port (default: 6001)
531
+ --user USER Database user (default: root)
532
+ --password PASSWORD Database password (default: 111)
533
+ --database DATABASE Database name (optional)
534
+ -d DATABASE Short form of --database
535
+ --log-level LEVEL Logging level (default: ERROR)
536
+ --command COMMAND Execute single command and exit
537
+ -c COMMAND Short form of --command
538
+ ```
539
+
540
+ ### Use Cases
541
+
542
+ #### 1. Monitor IVF Index Health in Production
543
+
544
+ ```bash
545
+ # Quick check on index status
546
+ mo-diag -d production -c "show_ivf_status -v"
547
+
548
+ # Detailed index inspection with physical table stats
549
+ mo-diag -d production -c "show_indexes my_vector_table"
550
+
551
+ # Verify centroid distribution balance
552
+ mo-diag -d production -c "show_ivf_status -t my_vector_table -v"
553
+ ```
554
+
555
+ #### 2. Debug Index Count Mismatches
556
+
557
+ ```bash
558
+ # Check row consistency
559
+ mo-diag -d test -c "verify_counts my_table"
560
+
561
+ # Get health report for all indexes
562
+ mo-diag -d test -c "show_all_indexes"
563
+
564
+ # Flush to sync if needed
565
+ mo-diag -d test -c "flush_table my_table"
566
+ ```
567
+
568
+ #### 3. Analyze Table Storage
569
+
570
+ ```bash
571
+ # Get table statistics with all indexes
572
+ mo-diag -d test -c "show_table_stats my_table -a"
573
+
574
+ # Detailed object-level analysis
575
+ mo-diag -d test -c "show_table_stats my_table -a -d"
576
+
577
+ # Include tombstone statistics
578
+ mo-diag -d test -c "show_table_stats my_table -a -t -d"
579
+ ```
580
+
581
+ #### 4. Automated Maintenance Scripts
582
+
583
+ ```bash
584
+ #!/bin/bash
585
+ # daily_index_check.sh
586
+
587
+ DATABASES=("prod_db1" "prod_db2" "prod_db3")
588
+
589
+ for db in "${DATABASES[@]}"; do
590
+ echo "Checking $db..."
591
+ mo-diag -d "$db" -c "show_all_indexes" >> /var/log/mo_diag_daily.log
592
+ mo-diag -d "$db" -c "show_ivf_status" >> /var/log/mo_diag_daily.log
593
+ done
594
+ ```
595
+
596
+ ### Tips and Best Practices
597
+
598
+ 1. **Regular Health Checks**: Run `show_all_indexes` daily to catch index issues early
599
+ 2. **Monitor IVF Balance**: Use `show_ivf_status -v` to ensure even centroid distribution
600
+ 3. **Before Major Operations**: Always `verify_counts` before bulk updates or migrations
601
+ 4. **Production Debugging**: Use non-interactive mode for logging and monitoring
602
+ 5. **Tab Completion**: Leverage Tab completion to avoid typos in table/database names
603
+ 6. **Command History**: Use `Ctrl+R` to quickly find and re-execute previous diagnostic commands
604
+ 7. **Flush Regularly**: If you notice index count mismatches, `flush_table` can help sync
605
+
606
+ ### Troubleshooting
607
+
608
+ **Issue**: Tab completion not working
609
+ - **Solution**: Ensure `prompt_toolkit>=3.0.0` is installed: `pip install prompt_toolkit`
610
+
611
+ **Issue**: "Unknown database" error
612
+ - **Solution**: Create the database first: `mo-diag -d test -c "sql CREATE DATABASE IF NOT EXISTS test"`
613
+
614
+ **Issue**: Permission denied for flush operations
615
+ - **Solution**: Connect as sys user or a user with sufficient privileges
616
+
617
+ **Issue**: IVF index shows 0 centroids
618
+ - **Solution**: The index might be empty or still building. Check with `show_table_stats <table> -a`
285
619
 
286
- ```python
287
- # Create PITR for cluster
288
620
  pitr = client.pitr.create_cluster_pitr(
289
621
  'cluster_pitr',
290
622
  range_value=7,
@@ -600,6 +932,15 @@ except Exception as e:
600
932
  print(f"Cleanup: {e}")
601
933
  ```
602
934
 
935
+
936
+ ## Advanced Features
937
+
938
+ ### PITR (Point-in-Time Recovery)
939
+
940
+ ```python
941
+ # Create PITR for cluster
942
+
943
+
603
944
  ## Configuration
604
945
 
605
946
  ### Connection Parameters