Getting Started with Marqo: Self-Host Semantic Search in 5 Minutes

Quick Start with Marqo

Marqo makes it incredibly easy to add semantic search to your applications. In this quick start guide, you will have Marqo running locally with Docker and indexing documents within minutes.

Prerequisites

• Docker installed on your machine
• Python 3.8+
• OpenSearch (used by Marqo as its storage backend)

Step 1: Start OpenSearch

Marqo relies on OpenSearch for storage and indexing. Start a single-node OpenSearch instance:

docker run -p 9200:9200 -p 9600:9600 -e "discovery.type=single-node" opensearchproject/opensearch:2.1.0

Step 2: Install the Marqo Python Client

pip install marqo

Step 3: Connect and Index Documents

Once both OpenSearch and the Marqo client are ready, you can start indexing documents with just a few lines of code:

import marqo

mq = marqo.Client(url='http://localhost:9200', main_user="admin", main_password="admin")

mq.index("my-first-index").add_documents([
    {
        "Title": "The Travels of Marco Polo",
        "Description": "A 13th-century travelogue describing Polo's travels"
    },
    {
        "Title": "Extravehicular Mobility Unit (EMU)",
        "Description": "The EMU is a spacesuit that provides environmental protection for astronauts"
    }
])

Step 4: Search

Searching is just as easy. Marqo handles semantic understanding automatically:

results = mq.index("my-first-index").search(
    q="What is the best outfit to wear on the moon?"
)

for hit in results['hits']:
    print(f"{hit['Title']}: {hit['_score']}")

Even though the query does not mention "spacesuit" directly, Marqo understands the semantic connection to "moon" and returns the EMU document as the top result. This is the power of neural search.

Deploying Marqo with Docker Compose

For a production-ready setup, you can use Docker Compose to run both Marqo and OpenSearch together:

version: '3'
services:
  marqo:
    image: marqoai/marqo:latest
    restart: unless-stopped
    ports:
      - 8080:8080
    volumes:
      - ./data/marqo:/data

Multi-Modal Search

Marqo also supports searching images with text. Create an index with a CLIP configuration to enable multi-modal search:

# Enable image indexing
settings = {
    "treat_urls_and_pointers_as_images": True,
    "model": "ViT-B/32"
}

mq.index("my-multimodal-index").add_documents([
    {"My Image": "https://example.com/cat.jpg"},
    {"My Image": "https://example.com/dog.jpg"}
])

# Search for images using text
results = mq.index("my-multimodal-index").search(
    'pet', searchable_attributes=['My Image']
)

Conclusion

Marqo makes semantic search accessible to every developer. With its simple Python API and Docker-based deployment, you can add powerful neural search to your applications in minutes — no machine learning expertise required. The Apache-2.0 license means you can use it freely in your projects, and self-hosting gives you full control over your data and infrastructure.