In Weaviate, when do you use near_text, near_vector, or near_object?

## The one idea behind all three A vector search needs exactly two things: a query vector and a collection to search. Weaviate exposes three query methods that differ *only* in how the query vector is obtained. Once the vector exists, the search path, the filtering, and the result shaping are identical. Understanding that collapses what looks like three APIs into one API with three front doors. ## near_text — the server embeds for you ```python response = collection.query.near_text(query="electric guitars", limit=5) ``` Weaviate takes the string, calls the vectorizer that was configured on the collection when it was created, gets back an embedding, and searches with it. This is the convenience path: you never touch an embedding model in your application code, and query-time and ingest-time embedding are guaranteed to use the same model because they are the same server-side configuration. The hard requirement is that the collection actually has a vectorizer. A collection created with no vectorizer stores only the vectors you supply, and `near_text` on it returns a server error saying no vectorizer is configured. This is the single most common first-day surprise with Weaviate. `near_text` also accepts `move_to` and `move_away` with `Move(force=..., concepts=[...])`, which nudge the query vector toward or away from extra concepts before the search runs — an option the other two front doors do not have, because they do not build the vector from text. ## near_vector — you embed ```python vec = my_model.encode("electric guitars") response = collection.query.near_vector(near_vector=vec, limit=5) ``` This is the explicit path. You own the embedding model, so you own the failure mode: the query vector must come from the same model, the same version, and the same dimensionality as the vectors stored in the collection. Mixing models silently produces garbage rankings rather than an error — the numbers are still floats of the right length, they just live in a different space. Dimension mismatches, by contrast, do fail loudly, because the collection's vector index has a fixed dimensionality. Use `near_vector` when embedding happens elsewhere in your pipeline (a batch job, a shared embedding service, a model you fine-tuned), when you want to search with a vector that is not the embedding of any text at all — an averaged user-preference vector, an image embedding, an arithmetic combination — or when you simply do not want the database making outbound calls to an embedding provider on the query path. ## near_object — reuse a stored vector ```python response = collection.query.near_object(near_object=some_uuid, limit=5) ``` Here the query vector is the vector Weaviate already holds for that object. No embedding call happens at all, which makes this the cheapest of the three. It is the natural implementation of "related articles", "similar products", or "more like this" on a detail page: you already know the UUID of the thing the user is looking at. One detail worth knowing: the source object itself is a perfect match for its own vector, so it normally comes back first. Either request `limit` + 1 and drop it client-side, or exclude it with a filter on its id. ## What they share Because the difference ends once the query vector exists, every result-shaping argument is common to all three: - `limit` and `offset` for how many results and where to start - `filters` for structured constraints, applied against the collection's inverted index - `distance` or `certainty` for a similarity cutoff - `auto_limit` for cutting the list where similarity drops off - `return_metadata=MetadataQuery(distance=True)` to see how close each hit actually was - `return_properties=[...]` to keep the payload small - `group_by` to fold results into groups A useful mental exercise before an interview: write the same search three ways and notice that only the first argument changes. ## Choosing in practice Reach for `near_text` when the collection is vectorized by the server and your query genuinely is text — it is the shortest correct code. Reach for `near_vector` when you control embeddings, when the query is not text, or when you need to keep the database off the network. Reach for `near_object` whenever the reference point is a row you already have, because re-embedding its text to search for its neighbours is pure waste and can even drift if the model changed since ingest.