Skip to main content
The openground query command performs hybrid search (semantic + BM25) against the local vector database.

​
Usage

openground query <query> [OPTIONS]

​
Arguments

​
query
string
required
Query string for hybrid search

​
Options

​
--version
string
default:"latest"
Version to filter results by.Aliases: -v
​
--library
string
default:"None"
Optional library name filter. If provided, only searches within this library.Aliases: -l
​
--top-k
integer
default:"5"
Number of results to return. Default value comes from configuration (query.top_k).Aliases: -kConstraints: Minimum value is 1

​
Search Algorithm

OpenGround uses hybrid search combining:
  1. Semantic Search: Vector similarity using embeddings
  2. BM25 (Keyword Search): Traditional full-text search
Results are ranked by combining both scores, providing relevant results even when exact keywords don’t match.

​
Examples

​
Basic Query

openground query "How to create a vector database"

​
Query Specific Library

openground query "authentication" --library langchain

​
Query Specific Version

openground query "new features" --version v2.0.0

​
Get More Results

openground query "embeddings" --top-k 10

​
Combined Options

openground query "API reference" -l mylib -v v1.5.0 -k 3

​
Output Format

Results are returned in markdown format with:
  • Title: Page title
  • URL: Source URL
  • Library & Version: Which library and version
  • Content: Relevant excerpt from the page

​
Output Example

# Result 1

**Title:** Vector Database Guide
**URL:** https://docs.example.com/vector-db
**Library:** mylib (v1.0.0)

Vector databases store high-dimensional embeddings and support 
semantic search queries. To create a vector database, you first 
need to generate embeddings for your documents...

---

# Result 2

**Title:** Embeddings Overview
**URL:** https://docs.example.com/embeddings
**Library:** mylib (v1.0.0)

Embeddings are numerical representations of text that capture 
semantic meaning. OpenGround supports multiple embedding backends...

​
Configuration

The default top_k value can be configured: 
openground config set query.top_k 10

​
Performance Tips

  1. Be Specific: More specific queries return better results
  2. Use Library Filter: Filter by library when you know which docs to search
  3. Adjust top_k: Increase for broader searches, decrease for focused results