{"id":4197,"library":"pymongo-search-utils","title":"PyMongo Search Utilities","description":"PyMongo Search Utils is a Python library designed to simplify working with vector search in MongoDB Atlas. It provides utilities for generating embeddings, constructing Atlas Search queries, and executing them via PyMongo. Currently at version 0.3.0, it's under active development with releases occurring as features and fixes are introduced, typically every few weeks.","status":"active","version":"0.3.0","language":"en","source_language":"en","source_url":"https://github.com/mongodb-developer/pymongo-search-utils","tags":["mongodb","pymongo","atlas search","vector search","embeddings","ai","search"],"install":[{"cmd":"pip install pymongo-search-utils[openai]","lang":"bash","label":"Install with OpenAI embedding support"},{"cmd":"pip install pymongo-search-utils[cohere]","lang":"bash","label":"Install with Cohere embedding support"},{"cmd":"pip install pymongo-search-utils","lang":"bash","label":"Install without specific embedding support"}],"dependencies":[{"reason":"Core dependency for interacting with MongoDB.","package":"pymongo>=4.0"},{"reason":"Required for vector operations.","package":"numpy","optional":false},{"reason":"Used for HTTP requests, potentially for external embedding services or metadata.","package":"requests","optional":false},{"reason":"For advanced type hints, especially for Python versions older than 3.10.","package":"typing_extensions","optional":false},{"reason":"Required for using `OpenAIEmbeddings`.","package":"openai","optional":true},{"reason":"Required for using `CohereEmbeddings`.","package":"cohere","optional":true}],"imports":[{"symbol":"AtlasSearch","correct":"from pymongo_search_utils import AtlasSearch"},{"symbol":"VectorSearch","correct":"from pymongo_search_utils.vector_search import VectorSearch"},{"symbol":"OpenAIEmbeddings","correct":"from pymongo_search_utils.embeddings import OpenAIEmbeddings"}],"quickstart":{"code":"import os\nimport pymongo\nfrom pymongo_search_utils import AtlasSearch\nfrom pymongo_search_utils.embeddings import OpenAIEmbeddings\n\n# Replace with your MongoDB Atlas connection string\nCONNECTION_STRING = os.environ.get(\"MONGO_URI\", \"mongodb://localhost:27017/\")\n\n# Replace with your OpenAI API key\nOPENAI_API_KEY = os.environ.get(\"OPENAI_API_KEY\", \"sk-YOUR_OPENAI_API_KEY\")\n\n# Connect to MongoDB Atlas\nclient = pymongo.MongoClient(CONNECTION_STRING)\ndb = client[\"mydatabase\"]\ncollection = db[\"mycollection\"]\n\n# Initialize OpenAI Embeddings\nembedding_service = OpenAIEmbeddings(openai_api_key=OPENAI_API_KEY)\n\n# Initialize AtlasSearch\natlas_search = AtlasSearch(\n    collection=collection,\n    index_name=\"default\", # Your Atlas Search index name\n    embedding_function=embedding_service,\n    vector_search_field=\"plot_embedding\", # The field in your collection containing vector embeddings\n    text_search_field=\"plot\" # The field in your collection for text search\n)\n\n# Example: Insert dummy data (if collection is empty)\nif collection.count_documents({}) == 0:\n    print(\"Inserting dummy data...\")\n    collection.insert_one({\"plot\": \"A dog goes on an adventure.\", \"plot_embedding\": embedding_service.embed_query(\"A dog goes on an adventure.\")})\n    collection.insert_one({\"plot\": \"Two friends discover a magical portal.\", \"plot_embedding\": embedding_service.embed_query(\"Two friends discover a magical portal.\")})\n    print(\"Dummy data inserted.\")\n\n# Perform a vector search\nquery = \"a furry companion's journey\"\nresults_vector = atlas_search.vector_search(query_string=query, limit=1)\n\nprint(f\"\\nVector Search Results for '{query}':\")\nfor doc in results_vector:\n    print(f\"  - Plot: {doc.get('plot')}\")\n\n# Perform a text search\nquery_text = \"magical portal\"\nresults_text = atlas_search.text_search(query_string=query_text, limit=1)\n\nprint(f\"\\nText Search Results for '{query_text}':\")\nfor doc in results_text:\n    print(f\"  - Plot: {doc.get('plot')}\")\n\nclient.close()","lang":"python","description":"This quickstart demonstrates how to connect to MongoDB Atlas, initialize `AtlasSearch` with an `OpenAIEmbeddings` function, and perform both vector and text searches. Remember to replace placeholder values for `CONNECTION_STRING`, `OPENAI_API_KEY`, `index_name`, `vector_search_field`, and `text_search_field`."},"warnings":[{"fix":"Ensure you are using a MongoDB Atlas cluster and have created an Atlas Search index (e.g., 'default' or a custom name) that includes vector search fields and text fields as needed.","message":"This library requires a MongoDB Atlas cluster with an Atlas Search index configured. It is not designed for self-hosted MongoDB for vector search features.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Install the library with the extra for your chosen embedding provider, e.g., `pip install pymongo-search-utils[openai]`.","message":"Embedding provider libraries (e.g., `openai`, `cohere`) must be explicitly installed via `pip install pymongo-search-utils[provider]` for the respective embedding functions to work.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Verify your Atlas Search index definition in the MongoDB Atlas UI matches the field names used in your `AtlasSearch` instance. Common mistake is `vector_search_field` being `vector` but the index defines `vector_embedding`.","message":"The `vector_search_field` and `text_search_field` parameters in `AtlasSearch` must correspond exactly to the field names configured in your Atlas Search index.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Consult the official GitHub repository's release notes for breaking changes and necessary code adjustments when upgrading to a newer 0.x.x version.","message":"As a pre-1.0 library (currently at 0.x.x), API interfaces may change in minor or patch releases without strict adherence to semantic versioning. Always review release notes when upgrading.","severity":"breaking","affected_versions":"<1.0.0"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}