{"id":9917,"library":"marqo","title":"Marqo","description":"Marqo is an open-source, RAG-ready vector database and tensor search engine built on OpenSearch. It enables multimodal search across text, images, and other data types using embeddings, simplifying the development of advanced search and Retrieval-Augmented Generation (RAG) applications. Currently at version 3.18.0, Marqo maintains an active development cycle with frequent updates and releases.","status":"active","version":"3.18.0","language":"en","source_language":"en","source_url":"https://github.com/marqo-ai/marqo","tags":["vector search","vector database","tensor search","AI","NLP","RAG"],"install":[{"cmd":"pip install marqo","lang":"bash","label":"Install Marqo client"}],"dependencies":[],"imports":[{"note":"The primary client class was renamed from `MarqoClient` to `Client` in Marqo v2.0.0. Using `MarqoClient` will result in an `ImportError` on newer versions.","wrong":"from marqo import MarqoClient","symbol":"Client","correct":"from marqo import Client"}],"quickstart":{"code":"import marqo\nimport os\n\n# For local Marqo instances (e.g., via Docker), the URL is often http://localhost:8882\n# For cloud instances, set MARQO_URL and optionally MARQO_API_KEY\nmarqo_url = os.environ.get('MARQO_URL', 'http://localhost:8882')\nmarqo_api_key = os.environ.get('MARQO_API_KEY', None)\n\nmq = marqo.Client(url=marqo_url, api_key=marqo_api_key)\n\nindex_name = \"my-first-marqo-index\"\n\n# Create an index (if it doesn't exist)\ntry:\n    mq.get_index(index_name=index_name)\n    print(f\"Index '{index_name}' already exists.\")\nexcept marqo.errors.MarqoApiError as e:\n    if \"index_not_found\" in str(e).lower():\n        print(f\"Creating index '{index_name}'...\")\n        mq.create_index(index_name=index_name)\n    else:\n        raise e\n\n\n# Add documents to the index\ndocs = [\n    {\n        \"_id\": \"doc1\",\n        \"title\": \"The Art of Computer Programming\",\n        \"description\": \"A series of comprehensive monographs by Donald Knuth covering many topics in computer science.\"\n    },\n    {\n        \"_id\": \"doc2\",\n        \"title\": \"Structure and Interpretation of Computer Programs\",\n        \"description\": \"An influential computer science textbook by Abelson and Sussman, known as SICP.\"\n    }\n]\n\nresponse_add = mq.add_documents(index_name=index_name, documents=docs)\nprint(\"Added documents:\", response_add)\n\n# Perform a search\nsearch_query = \"computer science textbooks\"\nresponse_search = mq.search(index_name=index_name, q=search_query)\nprint(f\"\\nSearch results for '{search_query}':\")\nfor hit in response_search['hits']:\n    print(f\"  Title: {hit['title']}, Score: {hit['_score']:.2f}\")\n\n# Clean up (optional): delete the index\n# mq.delete_index(index_name=index_name)","lang":"python","description":"This quickstart demonstrates how to initialize a Marqo client, create an index, add documents, and perform a basic search. It includes environment variable support for connecting to a Marqo instance and handles index creation idempotently."},"warnings":[{"fix":"Review your index creation code. Replace `model='some-model'` with `model_properties={'model': 'some-model'}`. Consult Marqo v2.x documentation for updated index settings.","message":"Marqo v2.0.0 introduced significant breaking changes to index settings, particularly regarding `model` and `model_properties`. The `model` parameter in `create_index` was moved into `model_properties` and `index_defaults` was removed.","severity":"breaking","affected_versions":"2.0.0 and above"},{"fix":"Update `create_index` calls. For example, `device='cuda'` should become `model_properties={'device': 'cuda'}`. Refer to Marqo v3.x documentation for the exact structure.","message":"Marqo v3.0.0 further refined index settings, specifically moving the `device` parameter. The `device` parameter in index settings (e.g., `device='cuda'`) was moved into `model_properties`.","severity":"breaking","affected_versions":"3.0.0 and above"},{"fix":"Ensure your environment (Docker Desktop, cloud VM) has sufficient RAM and CPU cores allocated. Monitor resource usage. Consider using smaller embedding models or a dedicated Marqo cloud instance for production workloads.","message":"Marqo relies on an underlying OpenSearch instance (often deployed via Docker). Resource consumption (memory, CPU) for Marqo itself and the embeddings models can be high, especially with larger models or heavy indexing/search loads.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Verify your Marqo Docker container is running (`docker ps`). Ensure the `url` parameter in `marqo.Client()` matches the Marqo instance's address and port (e.g., `http://localhost:8882` for a default local setup).","message":"When running Marqo locally with Docker, it's crucial that the Marqo container is running and accessible. Connection errors are often caused by the container not being started or the specified URL being incorrect.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Ensure your Marqo Docker container is running (e.g., `docker ps` to check). Verify the `url` in `marqo.Client()` is correct, usually `http://localhost:8882` for local setups.","cause":"The Marqo server (often a Docker container) is not running or is not accessible at the specified URL and port.","error":"urllib3.exceptions.MaxRetryError: HTTPConnectionPool(host='localhost', port=8882): Max retries exceeded with url: /indexes (Caused by NewConnectionError('<urllib3.connection.HTTPConnection object at ...>: Failed to establish a new connection: [Errno 111] Connection refused'))"},{"fix":"Check the index name for typos. If the index should exist, ensure `mq.create_index(index_name='your-index-name')` was called successfully before attempting other operations.","cause":"Attempted to access, add documents to, or search an index that has not been created or whose name is misspelled.","error":"marqo.errors.MarqoApiError: Could not find index 'my-non-existent-index'"},{"fix":"Update your `create_index` call to use the `model_properties` dictionary for specifying the model. Example: `mq.create_index(index_name, model_properties={'model': 'hf/e5-base'})`.","cause":"This error typically occurs in Marqo v2.0.0+ when using an older index creation schema where `model` was a top-level parameter, instead of being nested under `model_properties`.","error":"marqo.errors.MarqoApiError: Invalid model_properties: key model_properties.model. If model_properties.model is not specified, you must either specify it through the `model` param, or use default settings."}]}