Milvus Getting Started: Setup and First Vector Search (2026)

Getting started overview

Milvus is a vector database system designed to store, index, and manage massive embedding vectors generated by AI models. It facilitates efficient similarity search across large datasets, supporting applications such as recommendation systems, image recognition, and natural language processing. This guide focuses on the initial steps for setting up Milvus and executing a basic vector search operation.

Users have two primary deployment options: self-hosting the open-source Milvus software or utilizing Zilliz Cloud, a managed service that simplifies deployment and scaling. This guide will cover both approaches, with a focus on the managed service for quicker onboarding. Regardless of the deployment choice, the fundamental workflow involves establishing a connection, defining a collection (analogous to a table), inserting vector data, and performing a similarity search.

The following table outlines the key steps to get started with Milvus:

Create an account and get keys

For a managed Milvus experience, Zilliz Cloud offers a streamlined setup. Begin by navigating to the Zilliz Cloud signup page. You can register using your email address, Google account, or GitHub account. Upon successful registration, you will be directed to the Zilliz Cloud console.

Within the console, create a new project. Each project typically includes a default cluster. To obtain your connection credentials, select your project and navigate to the cluster details. You will find the following essential information:

• Endpoint: This is the address for connecting to your Milvus cluster (e.g., https://your-cluster-id.milvus.zillizcloud.com:19530).
• API Key/Token: This serves as your authentication credential. It is crucial for securing access to your Milvus instance.

Keep these credentials secure, as they will be required for all programmatic interactions with your Zilliz Cloud Milvus instance. The Milvus quickstart guide on connection details provides further information.

If you choose to self-host, follow the Milvus standalone Docker installation instructions. For local installations, default connection parameters typically include localhost and port 19530, and no API key is required by default, though securing it is recommended for production environments.

Your first request

This section demonstrates how to perform a basic vector search using the Python SDK (pymilvus) with a Zilliz Cloud instance. Ensure you have Python installed and then install the SDK:

pip install pymilvus faker

The faker library is used here to generate dummy data for demonstration purposes. Replace the placeholder values with your actual Zilliz Cloud endpoint and API key.

from pymilvus import MilvusClient, DataType, FieldSchema, CollectionSchema, Collection
from faker import Faker
import random

# 1. Zilliz Cloud Connection Details
CLUSTER_ENDPOINT = "YOUR_CLUSTER_ENDPOINT"  # e.g., "https://your-cluster-id.milvus.zillizcloud.com:19530"
API_KEY = "YOUR_API_KEY"  # Your Zilliz Cloud API Key

# Initialize Milvus Client
client = MilvusClient(
    uri=CLUSTER_ENDPOINT,
    token=API_KEY
)

COLLECTION_NAME = "example_collection"
DIMENSION = 128 # Dimension of your vectors

# 2. Define Collection Schema
# Check if collection exists, drop if it does for clean start
if client.has_collection(collection_name=COLLECTION_NAME):
    client.drop_collection(collection_name=COLLECTION_NAME)
    print(f"Dropped existing collection: {COLLECTION_NAME}")

fields = [
    FieldSchema(name="id", dtype=DataType.INT64, is_primary=True, auto_id=True),
    FieldSchema(name="vector", dtype=DataType.FLOAT_VECTOR, dim=DIMENSION),
    FieldSchema(name="title", dtype=DataType.VARCHAR, max_length=256),
    FieldSchema(name="category", dtype=DataType.VARCHAR, max_length=128)
]

schema = CollectionSchema(fields, description="An example collection for getting started")

# 3. Create Collection
client.create_collection(
    collection_name=COLLECTION_NAME,
    schema=schema,
    dimension=DIMENSION,
    metric_type="L2",  # L2, IP, COSINE, etc. based on your vector similarity needs
    index_type="AUTOINDEX" # Recommended for simplicity in quickstart
)
print(f"Collection '{COLLECTION_NAME}' created successfully.")

# 4. Prepare and Insert Data
faker = Faker()
num_entities = 100

data_to_insert = []
for i in range(num_entities):
    data_to_insert.append({
        "vector": [random.random() for _ in range(DIMENSION)],
        "title": faker.sentence(nb_words=6),
        "category": random.choice(["tech", "finance", "health", "education"])
    })

insert_result = client.insert(
    collection_name=COLLECTION_NAME,
    data=data_to_insert
)
print(f"Inserted {len(insert_result['insert_count'])} entities into '{COLLECTION_NAME}'.")

# 5. Prepare Search Vector
query_vector = [random.random() for _ in range(DIMENSION)]

# 6. Perform Similarity Search
search_results = client.search(
    collection_name=COLLECTION_NAME,
    data=[query_vector],
    limit=5,  # Return top 5 most similar results
    output_fields=["title", "category"],  # Fields to return with search results
    search_params={"metric_type": "L2", "params": {}}
)

print("\nSearch Results:")
for hit in search_results[0]:
    print(f"  ID: {hit['id']}, Distance: {hit['distance']:.4f}, Title: {hit['entity']['title']}, Category: {hit['entity']['category']}")

# Optional: Drop the collection to clean up
# client.drop_collection(collection_name=COLLECTION_NAME)
# print(f"Collection '{COLLECTION_NAME}' dropped.")

This Python script first connects to your Zilliz Cloud instance using the provided endpoint and API key. It then defines a schema for a new collection, creates the collection, inserts 100 randomly generated vector embeddings along with associated metadata, and finally performs a similarity search using a new query vector. The search returns the top 5 most similar entities, including their IDs, distances, titles, and categories.

Common next steps

After successfully executing your first Milvus request, consider these common next steps to further your integration and understanding:

1. Explore Indexing Options: Milvus supports various indexing algorithms (e.g., IVF_FLAT, HNSW) to optimize search performance for different datasets and query requirements. Refer to the Milvus indexing documentation to understand how to choose and apply appropriate indexes for your collections.
2. Implement Real-world Data: Replace the dummy data with actual vector embeddings from your application. This might involve integrating with embedding models (e.g., from TensorFlow, PyTorch, or OpenAI) to convert unstructured data (text, images, audio) into vectors.
3. Metadata Filtering: Enhance your similarity searches by adding metadata filters. Milvus allows you to combine vector similarity search with scalar filtering, enabling more precise results. The Milvus search documentation provides details on constructing boolean expressions for filtering.
4. Scalability and Production Deployment: For production environments, explore Milvus's distributed deployment options or leverage Zilliz Cloud's scaling capabilities. Understand concepts like sharding, replication, and load balancing to ensure high availability and performance. The Milvus cluster deployment guide offers insights into self-managed scaling.
5. Integrate with Applications: Integrate Milvus into your specific applications, such as recommendation engines, chatbots, or content moderation systems. The official Milvus example applications can provide inspiration and code patterns.
6. Monitoring and Management: Learn about monitoring your Milvus instance's health and performance. Zilliz Cloud provides built-in monitoring tools, while self-hosted Milvus can be integrated with standard monitoring solutions like Prometheus and Grafana.
7. Security Best Practices: Review security considerations, especially for production deployments. This includes network security, access control, and data encryption. For Zilliz Cloud, follow their security recommendations. For self-hosted Milvus, consider aspects like firewall rules and authentication mechanisms as described in the Milvus security documentation.
8. Explore Other SDKs: If Python is not your primary language, explore the Milvus SDKs for Java, Go, Node.js, or C++ to integrate Milvus into your preferred development environment.

Troubleshooting the first call

Encountering issues during your first Milvus call is common. Here are some troubleshooting tips:

• Incorrect Endpoint or API Key: Double-check that the CLUSTER_ENDPOINT and API_KEY in your code exactly match the credentials from your Zilliz Cloud console. Typos are a frequent cause of connection errors. Ensure there are no leading or trailing spaces.
• Network Connectivity: Verify that your development environment has network access to the Milvus cluster endpoint. If you are behind a corporate firewall or VPN, you might need to configure proxy settings or request firewall exceptions. For Zilliz Cloud, ensure your IP address is not blocked.
• SDK Installation Issues: Confirm that the pymilvus (or other language SDK) is correctly installed. Run pip list | grep pymilvus to check the installed version. If issues persist, try reinstalling with pip uninstall pymilvus && pip install pymilvus.
• Dimension Mismatch: The dimension of the vectors you insert and search with must match the DIMENSION specified when creating the collection. A mismatch will result in an error.
• Collection Already Exists: If you are running the example script multiple times without dropping the collection, the client.create_collection call will fail. The provided example includes a check and drop mechanism, but if removed, this could be an issue.
• Index Building Time: After inserting a large number of vectors, Milvus might take some time to build the index. During this period, search performance might not be optimal, or searches might return fewer results than expected until the index is fully operational.
• Resource Limits (Zilliz Cloud Free Tier): If you are using the Zilliz Cloud free tier, you might hit limits on compute units, storage, or requests. Check the Zilliz Cloud console for usage metrics. Exceeding these limits can lead to rejected requests. The Zilliz Cloud pricing page details these limits.
• Refer to Milvus Logs: For self-hosted Milvus, examine the Milvus server logs for detailed error messages. For Zilliz Cloud, the console might provide some logging or error details.
• Consult Documentation and Community: The Milvus troubleshooting guide is a valuable resource. Additionally, the Milvus community forums or Discord channel can provide assistance for specific issues.
• Python Environment: Ensure you are using the correct Python interpreter and virtual environment where pymilvus is installed. Sometimes, multiple Python installations can lead to confusion.