English for Weaviate Developers

Vector databases like Weaviate bring a vocabulary that mixes information retrieval terms (relevance, recall) with vector-math terms (distance metrics, dimensionality) — and a team building search or RAG features needs to speak both precisely, since “the search results are bad” can mean very different things depending on which layer the problem is in. This guide covers the English used when discussing Weaviate with a team.

Key Vocabulary

Vector embedding — a numeric representation of text, images, or other data produced by a model, positioned in a high-dimensional space so semantically similar items are close together. “The search is missing obvious synonyms because the embedding model was trained on a different domain — swapping to a domain-tuned model should fix the recall.”

Nearest neighbor search (ANN) — approximate nearest neighbor search, the algorithm class Weaviate uses to find the closest vectors to a query vector quickly, trading a small amount of accuracy for large speed gains over exact search. “At this collection size, exact nearest neighbor search is too slow for production — we need to tune the ANN index parameters instead of disabling approximation entirely.”

Distance metric — the function (cosine, dot product, Euclidean/L2) used to measure similarity between two vectors, which must match how the embedding model was trained to produce meaningful results. “We’re getting poor rankings because the collection is configured for L2 distance, but the embedding model was trained and normalized for cosine similarity.”

Hybrid search — combining vector similarity search with traditional keyword (BM25) search in a single query, usually blended with a weighting parameter, to catch both semantic matches and exact term matches. “Pure vector search missed the exact product SKU in the query — switching to hybrid search with a higher keyword weight should surface exact matches like that reliably.”

Schema class — Weaviate’s term for a collection type with a defined set of properties and vectorization configuration, analogous to a table in a relational database. “Before we add this new property to the schema class, remember that changing vectorized properties on an existing class usually requires re-indexing the whole collection.”

Certainty / score threshold — a cutoff applied to search results based on similarity score, used to exclude results that are technically the “nearest” but not actually relevant. “Returning the top ten results regardless of score is misleading the user when there are only two genuinely relevant matches — let’s apply a certainty threshold and show fewer, better results.”

Common Phrases

• “Does the distance metric here match how the embedding model was trained?”
• “Is this a recall problem with the embeddings, or a ranking problem with the query?”
• “Should this be a hybrid search instead of pure vector similarity?”
• “Does adding this property to the schema class require re-indexing?”
• “Are we applying a score threshold, or just returning the raw top-N regardless of relevance?”

Example Sentences

Reviewing a pull request: “This query returns the top twenty nearest neighbors unconditionally — let’s add a certainty threshold so we’re not surfacing barely-related results just to fill the count.”

Explaining a design decision: “We went with hybrid search because our users search by both natural language descriptions and exact part numbers, and pure vector search was missing the latter.”

Describing a bug: “Search quality dropped after the embedding model upgrade because we kept the old distance metric configuration — the new model expects cosine similarity, not the L2 we had configured.”

Professional Tips

• Say “recall” when the problem is relevant results not appearing at all, and “ranking” when relevant results appear but in the wrong order — conflating them sends debugging in the wrong direction.
• When reviewing search behavior, ask “does the distance metric match the embedding model’s training?” — mismatches here are a very common, easy-to-miss cause of poor results.
• Use “hybrid search” precisely to mean the combination of vector and keyword search — it’s a specific, named technique, not a vague description of “using two kinds of search.”
• Distinguish “ANN” (approximate nearest neighbor, the everyday production mode) from “exact nearest neighbor” (slower, used mainly for small collections or ground-truth comparison).

Practice Exercise

1. Explain in two sentences why a mismatched distance metric can degrade search quality even with a good embedding model.
2. Write a one-sentence recommendation for when to use hybrid search instead of pure vector search.
3. Describe, in your own words, the difference between a recall problem and a ranking problem.

In Practice: Navigating Nuances for Non-Native Speakers

Let’s be honest – professional development isn’t just about writing code. It’s about communicating that code effectively, collaborating with your team, and ensuring everyone understands the vision behind your work. For non-native English speakers, this can feel particularly challenging when grappling with the specialized vocabulary of vector search technologies like Weaviate. The words themselves might be relatively straightforward, but the subtle nuances of phrasing—the way ideas are presented in a code review, a Slack discussion, or even a pull request description—can significantly impact how your contributions are received and understood.

One common hurdle is the expectation around clarity within technical communication. Developers often use precise language to avoid ambiguity, but for someone whose first language isn’t English, this can come across as overly formal or even terse. It’s not about dumbing down explanations; it’s about ensuring your meaning is conveyed with maximum precision and minimal room for misinterpretation. For example, saying “This fixes the issue” is perfectly acceptable in a quick Slack message, but describing why you fixed it – detailing the root cause identified through vector similarity analysis—demonstrates deeper understanding and builds trust. Similarly, when reviewing someone else’s code, offering feedback like “The schema class could benefit from more granular indexing” is more constructive than simply stating “This needs work.” The latter lacks context and doesn’t explain how to improve it.

Another key area to focus on is the use of active versus passive voice. While passive phrasing isn’t inherently bad, overuse can make your writing feel convoluted and obscure accountability. Instead of saying “The data was indexed,” a clearer statement would be “We indexed the data using the weaviate CLI.” This highlights who performed the action and demonstrates familiarity with the tool. Furthermore, learning to articulate the rationale behind design decisions – especially those involving complex schema configurations or hybrid query strategies - is crucial for demonstrating your value within the team. Don’t just state what you did; explain why you chose that approach.

Finally, remember that documentation isn’t solely about technical specifications; it’s a collaborative effort to build shared understanding. When drafting PR descriptions, consider adding a brief summary of the architectural changes and how they align with the overall Weaviate strategy. This demonstrates your awareness of the broader context and encourages reviewers to quickly grasp the significance of your work.

weaviate cl i -c mydata -o "SELECT * FROM MySchema WHERE similarity($vector) > 0.8" --output json

This command illustrates a common scenario: using the weaviate CLI to execute a hybrid query—a combination of vector search and filtering based on specific criteria—to retrieve relevant data from the mydata dataset within the MySchema class. The output JSON provides concrete evidence of the search parameters used and the results obtained, facilitating discussion around performance optimization or schema adjustments.