<?xml version="1.0" encoding="utf-8"?>
<rss version="2.0" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/">
    <channel>
        <title>Weaviate Blog</title>
        <link>https://weaviate.io/blog</link>
        <description>Weaviate Blog</description>
        <lastBuildDate>Fri, 30 Oct 2026 00:00:00 GMT</lastBuildDate>
        <docs>https://validator.w3.org/feed/docs/rss2.html</docs>
        <generator>https://github.com/jpmonette/feed</generator>
        <language>en</language>
        <item>
            <title><![CDATA[Weaviate 1.40 Release]]></title>
            <link>https://weaviate.io/blog/weaviate-1-40-release</link>
            <guid>https://weaviate.io/blog/weaviate-1-40-release</guid>
            <pubDate>Fri, 30 Oct 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[Weaviate 1.40 makes dropping a named vector and 4-bit Rotational Quantization GA, adds multi-vector embeddings on HFresh and PathSeer filtering, and changes vector configuration defaults.]]></description>
            <content:encoded><![CDATA[
<!-- -->
<!-- -->
<p>Weaviate <code>v1.40</code> is now available open-source and on <a href="https://console.weaviate.cloud" target="_blank" rel="noopener noreferrer" class="">Weaviate Cloud</a>.</p>
<p>Two features reach <strong>general availability</strong> in this release: <strong>dropping a named vector</strong>, which frees the disk and index memory an unused vector was holding, and <strong>4-bit Rotational Quantization</strong>. Two more are new: the HFresh index now takes <strong>multi-vector embeddings</strong> through MUVERA, and <strong>PathSeer</strong> joins ACORN and sweeping as a third filter strategy for HNSW. This post also catches up on the <strong>Search REST API</strong>, which changed a lot over the 1.39 patch line. It also covers a <strong>breaking change to vector configuration defaults</strong> to check before you upgrade.</p>
<p>Here are the release highlights!</p>
<!-- -->
<p><img decoding="async" loading="lazy" alt="Weaviate 1.40 is released" src="/assets/images/hero-d1b147d84c067f8c00436b5fd88eaad6.png" width="1200" height="630" class="img_ev3q"></p>
<ul>
<li class=""><a href="#drop-a-named-vector---general-availability" class="">Drop a named vector - General Availability</a></li>
<li class=""><a href="#4-bit-rotational-quantization---general-availability" class="">4-bit Rotational Quantization - General Availability</a></li>
<li class=""><a href="#multi-vector-embeddings-on-hfresh-with-muvera" class="">Multi-vector embeddings on HFresh with MUVERA</a></li>
<li class=""><a href="#pathseer-filter-strategy" class="">PathSeer filter strategy</a></li>
<li class=""><a href="#search-rest-api-preview" class="">Search REST API (Preview)</a></li>
<li class=""><a href="#vector-configuration-defaults-breaking-change" class="">Vector configuration defaults (breaking change)</a></li>
<li class=""><a href="#performance-improvements-and-fixes" class="">Performance Improvements and Fixes</a></li>
<li class=""><a href="#community-contributions" class="">Community Contributions</a></li>
<li class=""><a href="#summary" class="">Summary</a></li>
</ul>
<div class="theme-admonition theme-admonition-caution admonition_xJq3 alert alert--warning"><div class="admonitionHeading_Gvgb"><span class="admonitionIcon_Rf37"><svg viewBox="0 0 16 16"><path fill-rule="evenodd" d="M8.893 1.5c-.183-.31-.52-.5-.887-.5s-.703.19-.886.5L.138 13.499a.98.98 0 0 0 0 1.001c.193.31.53.501.886.501h13.964c.367 0 .704-.19.877-.5a1.03 1.03 0 0 0 .01-1.002L8.893 1.5zm.133 11.497H6.987v-2.003h2.039v2.003zm0-3.004H6.987V5.987h2.039v4.006z"></path></svg></span>Breaking change</div><div class="admonitionContent_BuS1"><p>If your server sets <code>DEFAULT_VECTORIZER_MODULE</code>, read <a href="#vector-configuration-defaults-breaking-change" class="">Vector configuration defaults</a> before you upgrade.</p></div></div>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="drop-a-named-vector---general-availability">Drop a named vector - General Availability<a href="#drop-a-named-vector---general-availability" class="hash-link" aria-label="Direct link to Drop a named vector - General Availability" title="Direct link to Drop a named vector - General Availability" translate="no">​</a></h2>
<p>Collections pick up vectors over time. You add a named vector to try a new embedding model, the new one wins, and the old one stays on every object, in every shard, taking up disk and index memory. Until now the only way out was to re-create the collection and re-import everything.</p>
<p><code>v1.40</code> makes the <strong>drop vector index</strong> endpoint <strong>generally available</strong>. It has existed since <code>v1.37</code> as an experimental feature that was off by default. In <code>v1.40</code> it is on by default.</p>
<p>A drop deletes the vector's index and removes its embedding from every object. The collection's other named vectors and all object data stay as they are.</p>
<div class="theme-admonition theme-admonition-caution admonition_xJq3 alert alert--warning"><div class="admonitionHeading_Gvgb"><span class="admonitionIcon_Rf37"><svg viewBox="0 0 16 16"><path fill-rule="evenodd" d="M8.893 1.5c-.183-.31-.52-.5-.887-.5s-.703.19-.886.5L.138 13.499a.98.98 0 0 0 0 1.001c.193.31.53.501.886.501h13.964c.367 0 .704-.19.877-.5a1.03 1.03 0 0 0 .01-1.002L8.893 1.5zm.133 11.497H6.987v-2.003h2.039v2.003zm0-3.004H6.987V5.987h2.039v4.006z"></path></svg></span>A drop cannot be undone</div><div class="admonitionContent_BuS1"><p>To get the vector back, add it again and then re-vectorize or re-import your objects.</p></div></div>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="how-it-works">How it works<a href="#how-it-works" class="hash-link" aria-label="Direct link to How it works" title="Direct link to How it works" translate="no">​</a></h3>
<p>With the Python client (4.24.0 or newer), call <code>delete_vector_index</code> with the name of the vector:</p>
<div class="language-python codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-python codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token plain">articles </span><span class="token operator">=</span><span class="token plain"> client</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">collections</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">use</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token string" style="color:rgb(255, 121, 198)">"Article"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">articles</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">config</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">delete_vector_index</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token string" style="color:rgb(255, 121, 198)">"body_vector"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><br></span></code></pre></div></div>
<p>Over REST it is one <code>DELETE</code> request:</p>
<div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token plain">curl -X DELETE \</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">  http://localhost:8080/v1/schema/Article/vectors/body_vector/index</span><br></span></code></pre></div></div>
<p>The call returns once Weaviate has accepted the drop. The cleanup itself runs in the background, shard by shard, and picks up where it left off after a restart.</p>
<p>While the cleanup runs, the vector is still listed in the collection definition, and writes that target it are rejected. In a batch, only the objects that carry the dropped vector fail. The drop is finished when the vector disappears from the definition.</p>
<p>A few more things to know:</p>
<ul>
<li class=""><strong>Permissions:</strong> You need <code>update</code> permission on the collection and on its data objects, because a drop rewrites every object.</li>
<li class=""><strong>Inactive tenants:</strong> A tenant that is inactive holds up completion until it is activated and a later cleanup round reaches it.</li>
<li class=""><strong>Reusing the name:</strong> Once the drop is finished you can add a vector with the same name again, even with a different dimensionality. The new index starts empty.</li>
<li class=""><strong>The last vector:</strong> Dropping the only vector leaves a collection with no vectors. Objects and properties stay.</li>
</ul>
<p>The Python client is the first to wrap the endpoint. From any other language, send the REST request.</p>
<!-- -->
<div class="theme-admonition theme-admonition-info admonition_xJq3 alert alert--info"><div class="admonitionHeading_Gvgb"><span class="admonitionIcon_Rf37"><svg viewBox="0 0 14 16"><path fill-rule="evenodd" d="M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"></path></svg></span>Related resources</div><div class="admonitionContent_BuS1"><ul>
<li class=""><a href="https://docs.weaviate.io/weaviate/manage-collections/vector-config#drop-a-named-vector" target="_blank" rel="noopener noreferrer" class="">How-to: Manage collections - Drop a named vector</a></li>
<li class=""><a href="https://docs.weaviate.io/weaviate/api/rest#tag/schema" target="_blank" rel="noopener noreferrer" class="">References: RESTful API - Schema</a></li>
</ul></div></div>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="4-bit-rotational-quantization---general-availability">4-bit Rotational Quantization - General Availability<a href="#4-bit-rotational-quantization---general-availability" class="hash-link" aria-label="Direct link to 4-bit Rotational Quantization - General Availability" title="Direct link to 4-bit Rotational Quantization - General Availability" translate="no">​</a></h2>
<p><a class="" href="/blog/weaviate-1-39-release#4-bit-rotational-quantization-preview">4-bit Rotational Quantization (RQ)</a>, a preview in <code>v1.39</code>, is now <strong>generally available</strong>. RQ rotates each vector, then stores every dimension as a small integer instead of a full float.</p>
<p>The reason to turn it on is memory. On a million 1536-dimension vectors, 4-bit RQ used about 45% less memory than 8-bit RQ. A cluster of the same size holds more vectors, or you run a smaller one. Imports get faster too.</p>
<p>Search quality holds up because Weaviate rescores the best candidates with the original vectors.</p>
<!-- -->
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="how-it-works-1">How it works<a href="#how-it-works-1" class="hash-link" aria-label="Direct link to How it works" title="Direct link to How it works" translate="no">​</a></h3>
<p>Many embedding models produce vectors that cluster around a point that is not zero. Centering, in Weaviate since <code>v1.39.3</code>, measures that point from a sample of your data and compresses relative to it. That brings 4-bit recall close to 8-bit. It is off by default because some models already do this. It only applies to 4-bit.</p>
<p>Set <code>rq.bits = 4</code> on an HNSW index. With Python client 4.23.1 or newer, turn on centering in the same call:</p>
<div class="language-python codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-python codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">from</span><span class="token plain"> weaviate</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">classes</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">config </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">import</span><span class="token plain"> Configure</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">client</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">collections</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">create</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    </span><span class="token string" style="color:rgb(255, 121, 198)">"Doc"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    vector_config</span><span class="token operator">=</span><span class="token plain">Configure</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">Vectors</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">self_provided</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">        name</span><span class="token operator">=</span><span class="token string" style="color:rgb(255, 121, 198)">"default"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">        vector_index_config</span><span class="token operator">=</span><span class="token plain">Configure</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">VectorIndex</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">hnsw</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">            quantizer</span><span class="token operator">=</span><span class="token plain">Configure</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">VectorIndex</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">Quantizer</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">rq</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain">bits</span><span class="token operator">=</span><span class="token number">4</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> centering</span><span class="token operator">=</span><span class="token boolean">True</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">        </span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    </span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><br></span></code></pre></div></div>
<p><code>bits</code> locks when RQ is first enabled on a vector, so pick the width before then. You can still enable RQ later on an uncompressed collection.</p>
<p>Operators can set <code>DEFAULT_QUANTIZATION=rq-4</code> to make 4-bit RQ the default for new HNSW indexes. Weaviate Cloud keeps 8-bit RQ as its default. 4-bit works on HNSW indexes only.</p>
<p>The numbers and the engineering are in the <a class="" href="/blog/4-bit-rotational-quantization">4-bit Rotational Quantization deep dive</a>.</p>
<div class="theme-admonition theme-admonition-info admonition_xJq3 alert alert--info"><div class="admonitionHeading_Gvgb"><span class="admonitionIcon_Rf37"><svg viewBox="0 0 14 16"><path fill-rule="evenodd" d="M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"></path></svg></span>Related resources</div><div class="admonitionContent_BuS1"><ul>
<li class=""><a href="https://docs.weaviate.io/weaviate/concepts/vector-quantization#rotational-quantization" target="_blank" rel="noopener noreferrer" class="">Concepts: Vector quantization - Rotational quantization</a></li>
<li class=""><a href="https://docs.weaviate.io/weaviate/configuration/compression/rq-compression#4-bit-rq" target="_blank" rel="noopener noreferrer" class="">How-to: Compression - 4-bit RQ</a></li>
<li class=""><a class="" href="/blog/4-bit-rotational-quantization">Blog: 4-bit Rotational Quantization</a></li>
</ul></div></div>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="multi-vector-embeddings-on-hfresh-with-muvera">Multi-vector embeddings on HFresh with MUVERA<a href="#multi-vector-embeddings-on-hfresh-with-muvera" class="hash-link" aria-label="Direct link to Multi-vector embeddings on HFresh with MUVERA" title="Direct link to Multi-vector embeddings on HFresh with MUVERA" translate="no">​</a></h2>
<p><a class="" href="/blog/hfresh">HFresh</a> is Weaviate's disk-based vector index. It keeps a small index of centroids in memory and stores compressed vectors on disk, so it needs far less memory than HNSW. Until now it only took one vector per object.</p>
<p>Late-interaction models such as ColBERT and ColPali produce a <strong>multi-vector embedding</strong>: one vector per token or image patch, instead of one vector per object. They rank well, but a page of text can turn into hundreds of vectors, which is the kind of data that strains memory. In <code>v1.40</code>, HFresh can index them.</p>
<p>There is one condition. On HFresh, multi-vector embeddings need <strong>MUVERA</strong> encoding. MUVERA turns a set of vectors into a single fixed-length vector, so HFresh can search it like any other.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="how-it-works-2">How it works<a href="#how-it-works-2" class="hash-link" aria-label="Direct link to How it works" title="Direct link to How it works" translate="no">​</a></h3>
<p>A multi-vector query on HFresh runs in three passes:</p>
<!-- -->
<p><code>searchProbe</code> and <code>rq.rescoreLimit</code>, both set in the HFresh index config, control the first two passes. <code>searchProbe</code> sets how many posting lists are scanned. <code>rq.rescoreLimit</code> sets how many candidates survive the rescore. The survivors are then scored exactly against their original token vectors with MaxSim. MaxSim is the late-interaction score that matches each query token to its closest document token.</p>
<p>To set it up, create a named vector with no vectorizer, MUVERA encoding, and an HFresh index:</p>
<div class="language-python codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-python codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">from</span><span class="token plain"> weaviate</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">classes</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">config </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">import</span><span class="token plain"> Configure</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">client</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">collections</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">create</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    </span><span class="token string" style="color:rgb(255, 121, 198)">"Page"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    vector_config</span><span class="token operator">=</span><span class="token plain">Configure</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">MultiVectors</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">self_provided</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">        name</span><span class="token operator">=</span><span class="token string" style="color:rgb(255, 121, 198)">"colbert"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">        encoding</span><span class="token operator">=</span><span class="token plain">Configure</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">VectorIndex</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">MultiVector</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">Encoding</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">muvera</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">        vector_index_config</span><span class="token operator">=</span><span class="token plain">Configure</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">VectorIndex</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">hfresh</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    </span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><br></span></code></pre></div></div>
<p>The constraints:</p>
<ul>
<li class=""><strong>The vector needs <code>"vectorizer": "none"</code>:</strong> You bring the token vectors yourself.</li>
<li class=""><strong>MUVERA is required, and fixed at creation:</strong> <code>multivector.muvera.enabled</code> cannot be changed later.</li>
<li class=""><strong>The encoding is always compressed with 1-bit RQ:</strong> PQ, SQ and BQ are rejected, and RQ cannot be turned off.</li>
</ul>
<div class="theme-admonition theme-admonition-caution admonition_xJq3 alert alert--warning"><div class="admonitionHeading_Gvgb"><span class="admonitionIcon_Rf37"><svg viewBox="0 0 16 16"><path fill-rule="evenodd" d="M8.893 1.5c-.183-.31-.52-.5-.887-.5s-.703.19-.886.5L.138 13.499a.98.98 0 0 0 0 1.001c.193.31.53.501.886.501h13.964c.367 0 .704-.19.877-.5a1.03 1.03 0 0 0 .01-1.002L8.893 1.5zm.133 11.497H6.987v-2.003h2.039v2.003zm0-3.004H6.987V5.987h2.039v4.006z"></path></svg></span><code>multivector.enabled</code> alone is not enough on HFresh</div><div class="admonitionContent_BuS1"><p>If you set <code>multivector.enabled</code> without MUVERA, the collection is created, but it behaves as a regular vector without multi-vector support and rejects multi-vector imports and queries. Set <code>multivector.muvera.enabled</code>.</p></div></div>
<div class="theme-admonition theme-admonition-info admonition_xJq3 alert alert--info"><div class="admonitionHeading_Gvgb"><span class="admonitionIcon_Rf37"><svg viewBox="0 0 14 16"><path fill-rule="evenodd" d="M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"></path></svg></span>Related resources</div><div class="admonitionContent_BuS1"><ul>
<li class=""><a href="https://docs.weaviate.io/weaviate/config-refs/indexing/vector-index#hfresh-multi-vector" target="_blank" rel="noopener noreferrer" class="">Config references: Multi-vector embeddings on HFresh</a></li>
<li class=""><a href="https://docs.weaviate.io/weaviate/concepts/vector-index#multi-vector-embeddings-on-hfresh" target="_blank" rel="noopener noreferrer" class="">Concepts: Multi-vector embeddings on HFresh</a></li>
<li class=""><a href="https://docs.weaviate.io/weaviate/configuration/compression/multi-vectors#muvera-encoding" target="_blank" rel="noopener noreferrer" class="">How-to: Multi-vector compression - MUVERA encoding</a></li>
<li class=""><a class="" href="/blog/hfresh">Blog: HFresh, memory-efficient vector search</a></li>
</ul></div></div>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="pathseer-filter-strategy">PathSeer filter strategy<a href="#pathseer-filter-strategy" class="hash-link" aria-label="Direct link to PathSeer filter strategy" title="Direct link to PathSeer filter strategy" translate="no">​</a></h2>
<p>A filtered vector search has to find the nearest objects that also pass a filter. On an HNSW index, the <code>filterStrategy</code> setting decides how the search walks the graph when many neighbors fail the filter. Until now you had two choices: <code>acorn</code> (the default) and <code>sweeping</code>.</p>
<p><code>v1.40</code> adds a third, <strong><code>pathseer</code></strong>. It comes from the <a href="https://doi.org/10.1145/3802098" target="_blank" rel="noopener noreferrer" class="">SIGMOD 2026 paper</a> by Zhiyue Li et al., and the paper's first author, <a href="https://github.com/lizhiyuell" target="_blank" rel="noopener noreferrer" class="">@lizhiyuell</a>, contributed the implementation (<a href="https://github.com/weaviate/weaviate/pull/12137" target="_blank" rel="noopener noreferrer" class="">#12137</a>).</p>
<p>In Weaviate's benchmarks PathSeer was the fastest strategy, or within a few percent of it, on random, topical and combined filters. ACORN stays ahead only on strongly negatively correlated filters, where the filter all but excludes the query's neighborhood. The <a class="" href="/blog/pathseer-filtered-vector-search">PathSeer post</a> has the full benchmarks and a walkthrough of the algorithm.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="how-it-works-3">How it works<a href="#how-it-works-3" class="hash-link" aria-label="Direct link to How it works" title="Direct link to How it works" translate="no">​</a></h3>
<p>PathSeer walks the bottom layer of the graph like sweeping. While the result set is still filling, it also filter-checks the neighbors of each candidate's neighbors, like ACORN. Once the result set is full, it skips the non-matching neighbors of a non-matching candidate without computing their distance. It makes that call per node, so there is no new parameter to tune.</p>
<p>It stores nothing extra. There is no import cost, no memory overhead, and you can switch an existing collection to it, or away from it, without reindexing. The flat-search cutoff still applies first: when a filter matches fewer objects than <code>flatSearchCutoff</code>, Weaviate scans those objects instead of walking the graph.</p>
<p>To switch an existing named vector over:</p>
<div class="language-python codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-python codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">from</span><span class="token plain"> weaviate</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">classes</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">config </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">import</span><span class="token plain"> Reconfigure</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> VectorFilterStrategy</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">articles </span><span class="token operator">=</span><span class="token plain"> client</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">collections</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">use</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token string" style="color:rgb(255, 121, 198)">"Article"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">articles</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">config</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">update</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    vector_config</span><span class="token operator">=</span><span class="token plain">Reconfigure</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">Vectors</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">update</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">        name</span><span class="token operator">=</span><span class="token string" style="color:rgb(255, 121, 198)">"default"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">        vector_index_config</span><span class="token operator">=</span><span class="token plain">Reconfigure</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">VectorIndex</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">hnsw</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">            filter_strategy</span><span class="token operator">=</span><span class="token plain">VectorFilterStrategy</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">PATHSEER</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">        </span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    </span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><br></span></code></pre></div></div>
<p>In a collection definition sent over REST, it is one field in the HNSW <code>vectorIndexConfig</code>:</p>
<div class="language-json codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-json codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token punctuation" style="color:rgb(248, 248, 242)">{</span><span class="token plain"> </span><span class="token property">"vectorIndexConfig"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">{</span><span class="token plain"> </span><span class="token property">"filterStrategy"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:rgb(255, 121, 198)">"pathseer"</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">}</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">}</span><br></span></code></pre></div></div>
<div class="theme-admonition theme-admonition-info admonition_xJq3 alert alert--info"><div class="admonitionHeading_Gvgb"><span class="admonitionIcon_Rf37"><svg viewBox="0 0 14 16"><path fill-rule="evenodd" d="M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"></path></svg></span>Related resources</div><div class="admonitionContent_BuS1"><ul>
<li class=""><a href="https://docs.weaviate.io/weaviate/concepts/filtering#pathseer" target="_blank" rel="noopener noreferrer" class="">Concepts: Filtering - PathSeer</a></li>
<li class=""><a class="" href="/blog/pathseer-filtered-vector-search">Blog: PathSeer, adaptive filtered vector search</a></li>
</ul></div></div>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="search-rest-api-preview">Search REST API (Preview)<a href="#search-rest-api-preview" class="hash-link" aria-label="Direct link to Search REST API (Preview)" title="Direct link to Search REST API (Preview)" translate="no">​</a></h2>
<p>The <a class="" href="/blog/weaviate-1-39-release#search-rest-api-experimental">Search REST API</a> lets you search with plain JSON over HTTP/1.1, with no generated client and no GraphQL query strings. It arrived as an experimental, off-by-default feature in <code>v1.39</code>. A lot has changed since then. All of it shipped in 1.39 patches, and the API is now a <strong>preview</strong>.</p>
<ul>
<li class=""><strong>On by default from <code>v1.39.7</code></strong></li>
<li class=""><strong>Structured references from <code>v1.39.3</code>:</strong> A new <code>returnReferences</code> field replaces the dotted <code>"hasAuthor.name"</code> form the 1.39 post warned about. A dotted name in <code>returnProperties</code> is now rejected.</li>
<li class=""><strong><code>near-vector</code> from <code>v1.39.8</code>:</strong> It takes a vector you supply, so it works on collections without a vectorizer.</li>
</ul>
<p>That makes six endpoints:</p>
<ul>
<li class=""><code>POST /v1/search/{collection}/near-text</code></li>
<li class=""><code>POST /v1/search/{collection}/bm25</code></li>
<li class=""><code>POST /v1/search/{collection}/hybrid</code></li>
<li class=""><code>POST /v1/search/{collection}/near-object</code></li>
<li class=""><code>POST /v1/search/{collection}/near-vector</code></li>
<li class=""><code>POST /v1/aggregate/{collection}</code> (returns a count)</li>
</ul>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="how-it-works-4">How it works<a href="#how-it-works-4" class="hash-link" aria-label="Direct link to How it works" title="Direct link to How it works" translate="no">​</a></h3>
<p>Here is a <code>near-vector</code> search that also follows a reference to each book's author:</p>
<div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token plain">curl -s -X POST http://localhost:8080/v1/search/Book/near-vector \</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">  -H 'Content-Type: application/json' \</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">  -d '{"vector":[0.1,0.9,0.2],"limit":1,</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">       "returnProperties":["title"],</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">       "returnReferences":[{"linkOn":"writtenBy","returnProperties":["name"]}],</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">       "returnMetadata":["distance"]}'</span><br></span></code></pre></div></div>
<p>Each <code>returnReferences</code> entry names the reference property in <code>linkOn</code> and what to return from the objects it points to. You can also set <code>targetCollection</code> for a multi-target reference, <code>returnMetadata</code> for the referenced objects, and a nested <code>returnReferences</code> to go one hop further. Referenced objects come back in the same <code>properties</code> and <code>metadata</code> shape as the top-level hits:</p>
<div class="language-json codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-json codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token punctuation" style="color:rgb(248, 248, 242)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">  </span><span class="token property">"results"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">[</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    </span><span class="token punctuation" style="color:rgb(248, 248, 242)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">      </span><span class="token property">"id"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:rgb(255, 121, 198)">"ce442a4d-a704-46bd-b5c3-cf7b1b2ffdc0"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">      </span><span class="token property">"metadata"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">{</span><span class="token plain"> </span><span class="token property">"distance"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token number">0.00040352345</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">}</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">      </span><span class="token property">"properties"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">{</span><span class="token plain"> </span><span class="token property">"title"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:rgb(255, 121, 198)">"The Left Hand of Darkness"</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">}</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">      </span><span class="token property">"references"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">        </span><span class="token property">"writtenBy"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">[</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">{</span><span class="token plain"> </span><span class="token property">"properties"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">{</span><span class="token plain"> </span><span class="token property">"name"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:rgb(255, 121, 198)">"Ursula K. Le Guin"</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">}</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">}</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">]</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">      </span><span class="token punctuation" style="color:rgb(248, 248, 242)">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    </span><span class="token punctuation" style="color:rgb(248, 248, 242)">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">  </span><span class="token punctuation" style="color:rgb(248, 248, 242)">]</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">  </span><span class="token property">"tookMs"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token number">1</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token punctuation" style="color:rgb(248, 248, 242)">}</span><br></span></code></pre></div></div>
<p>A few things have not changed. The default <code>limit</code> is <code>QUERY_DEFAULTS_LIMIT</code> (10). <code>targetVector</code> takes a single vector name. No client library wraps these endpoints yet. Boost, MMR, reranking, generative search and grouped search are not available over REST.</p>
<div class="theme-admonition theme-admonition-caution admonition_xJq3 alert alert--warning"><div class="admonitionHeading_Gvgb"><span class="admonitionIcon_Rf37"><svg viewBox="0 0 16 16"><path fill-rule="evenodd" d="M8.893 1.5c-.183-.31-.52-.5-.887-.5s-.703.19-.886.5L.138 13.499a.98.98 0 0 0 0 1.001c.193.31.53.501.886.501h13.964c.367 0 .704-.19.877-.5a1.03 1.03 0 0 0 .01-1.002L8.893 1.5zm.133 11.497H6.987v-2.003h2.039v2.003zm0-3.004H6.987V5.987h2.039v4.006z"></path></svg></span>Preview</div><div class="admonitionContent_BuS1"><p>The Search REST API is a <strong>preview</strong> feature. Its request and response shape may still change in future releases.</p></div></div>
<div class="theme-admonition theme-admonition-info admonition_xJq3 alert alert--info"><div class="admonitionHeading_Gvgb"><span class="admonitionIcon_Rf37"><svg viewBox="0 0 14 16"><path fill-rule="evenodd" d="M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"></path></svg></span>Related resources</div><div class="admonitionContent_BuS1"><ul>
<li class=""><a href="https://docs.weaviate.io/weaviate/api/rest#tag/search" target="_blank" rel="noopener noreferrer" class="">References: RESTful API - Search endpoints</a></li>
</ul></div></div>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="vector-configuration-defaults-breaking-change">Vector configuration defaults (breaking change)<a href="#vector-configuration-defaults-breaking-change" class="hash-link" aria-label="Direct link to Vector configuration defaults (breaking change)" title="Direct link to Vector configuration defaults (breaking change)" translate="no">​</a></h2>
<div class="theme-admonition theme-admonition-caution admonition_xJq3 alert alert--warning"><div class="admonitionHeading_Gvgb"><span class="admonitionIcon_Rf37"><svg viewBox="0 0 16 16"><path fill-rule="evenodd" d="M8.893 1.5c-.183-.31-.52-.5-.887-.5s-.703.19-.886.5L.138 13.499a.98.98 0 0 0 0 1.001c.193.31.53.501.886.501h13.964c.367 0 .704-.19.877-.5a1.03 1.03 0 0 0 .01-1.002L8.893 1.5zm.133 11.497H6.987v-2.003h2.039v2.003zm0-3.004H6.987V5.987h2.039v4.006z"></path></svg></span>Check this before you upgrade</div><div class="admonitionContent_BuS1"><p>If your server sets <code>DEFAULT_VECTORIZER_MODULE</code>, collections you create on <code>v1.40</code> without naming a vectorizer will <strong>not</strong> be vectorized. There is no error at creation time, only a warning at startup.</p></div></div>
<p>From <code>v1.40</code>, <code>DEFAULT_VECTORIZER_MODULE</code> is deprecated and ignored. Weaviate logs a warning at startup if it is set. The default top-level <code>vectorizer</code> is always <code>none</code>. Existing collections are not affected. What changes is what a new collection definition gives you:</p>
<table><thead><tr><th style="text-align:left">Your collection definition sets</th><th style="text-align:left">Before <code>v1.40</code></th><th style="text-align:left">From <code>v1.40</code></th></tr></thead><tbody><tr><td style="text-align:left">No vector parameters at all</td><td style="text-align:left">A single-vector collection, filled in from the server defaults</td><td style="text-align:left">A collection without a vector</td></tr><tr><td style="text-align:left"><code>vectorIndexType</code> or <code>vectorIndexConfig</code>, but no <code>vectorizer</code></td><td style="text-align:left">A single-vector collection, vectorized by <code>DEFAULT_VECTORIZER_MODULE</code></td><td style="text-align:left">A single-vector collection that does not vectorize</td></tr><tr><td style="text-align:left">An explicit vectorizer</td><td style="text-align:left">Unchanged</td><td style="text-align:left">Unchanged</td></tr></tbody></table>
<p>Older clients that always send <code>vectorIndexType</code>, such as the Python client before <code>4.21.2</code>, land in the second row. Auto-schema changed earlier: since <code>v1.39.1</code> it creates a named vector called <code>default</code> with the vectorizer set to <code>none</code>.</p>
<p><strong>What to do:</strong> name the vectorizer explicitly in every collection definition that needs one, before you upgrade.</p>
<div class="theme-admonition theme-admonition-info admonition_xJq3 alert alert--info"><div class="admonitionHeading_Gvgb"><span class="admonitionIcon_Rf37"><svg viewBox="0 0 14 16"><path fill-rule="evenodd" d="M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"></path></svg></span>Related resources</div><div class="admonitionContent_BuS1"><ul>
<li class=""><a href="https://docs.weaviate.io/deploy/migration#vector-config-defaults" target="_blank" rel="noopener noreferrer" class="">Migration guide: Vector configuration defaults</a></li>
<li class=""><a href="https://docs.weaviate.io/weaviate/config-refs/collections#no-vector" target="_blank" rel="noopener noreferrer" class="">Config references: Collections without a vector</a></li>
</ul></div></div>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="performance-improvements-and-fixes">Performance Improvements and Fixes<a href="#performance-improvements-and-fixes" class="hash-link" aria-label="Direct link to Performance Improvements and Fixes" title="Direct link to Performance Improvements and Fixes" translate="no">​</a></h2>
<p>Beyond the headline features, <code>v1.40</code> ships a long list of improvements. Some of the items below first shipped in 1.39 patches, and those say so. A few worth calling out:</p>
<ul>
<li class=""><strong>Shard status per replica:</strong> <code>GET /v1/schema/{collection}/shards</code> now reports a <code>per_node_status</code> object that maps each node to the shard's status on that node. A replica that cannot be reached, or cannot serve reads, reports <code>UNAVAILABLE</code>. The old <code>status</code> and <code>vectorQueueSize</code> fields are deprecated.</li>
<li class=""><strong>Stricter MCP hybrid tool:</strong> the built-in MCP server's hybrid search tool now rejects an <code>alpha</code> outside <code>0</code> to <code>1</code> and a negative <code>limit</code>. It combines results with relative score fusion, the same default as the other APIs, and it rejects unknown argument keys.</li>
<li class=""><strong>gRPC for Google Cloud Storage backups:</strong> the <code>backup-gcs</code> module now talks to GCS over gRPC by default. A local emulator that only serves the JSON API needs <code>GCS_MODULE_TRANSPORT=http</code>.</li>
<li class=""><strong>Smaller HNSW graph in memory:</strong> each HNSW node is now a single heap object instead of three, which means less memory per node and fewer allocations. Shipped in <code>v1.39.6</code>.</li>
<li class=""><strong>Leaner aggregations:</strong> aggregation scans now reuse their buffers and read each segment through a single reader, so they allocate much less. Shipped in <code>v1.39.3</code>.</li>
<li class=""><strong>A <code>read_backups</code> permission:</strong> a role can now list backups and read backup and restore status without being able to create, restore or cancel one. Shipped in <code>v1.39.10</code>.</li>
<li class=""><strong>Two new generative modules:</strong> <a href="https://docs.weaviate.io/weaviate/model-providers/digitalocean/generative" target="_blank" rel="noopener noreferrer" class="">DigitalOcean</a> arrived in <code>v1.39.2</code> and <a href="https://docs.weaviate.io/weaviate/model-providers/meta/generative" target="_blank" rel="noopener noreferrer" class="">Meta AI</a> in <code>v1.39.3</code>.</li>
</ul>
<div class="theme-admonition theme-admonition-info admonition_xJq3 alert alert--info"><div class="admonitionHeading_Gvgb"><span class="admonitionIcon_Rf37"><svg viewBox="0 0 14 16"><path fill-rule="evenodd" d="M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"></path></svg></span>Related resources</div><div class="admonitionContent_BuS1"><ul>
<li class=""><a href="https://github.com/weaviate/weaviate/releases/tag/v1.40.0" target="_blank" rel="noopener noreferrer" class="">Weaviate 1.40: GitHub Release Notes</a></li>
</ul></div></div>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="community-contributions">Community Contributions<a href="#community-contributions" class="hash-link" aria-label="Direct link to Community Contributions" title="Direct link to Community Contributions" translate="no">​</a></h2>
<p>Weaviate is open source, and this release cycle includes work from four first-time contributors. Thank you to:</p>
<ul>
<li class=""><a href="https://github.com/lizhiyuell" target="_blank" rel="noopener noreferrer" class="">@lizhiyuell</a>: the PathSeer filter strategy for HNSW (<a href="https://github.com/weaviate/weaviate/pull/12137" target="_blank" rel="noopener noreferrer" class="">#12137</a>)</li>
<li class=""><a href="https://github.com/hamodywe" target="_blank" rel="noopener noreferrer" class="">@hamodywe</a>: fetching <code>Boost.Depth</code>-deep candidates in hybrid sub-searches (<a href="https://github.com/weaviate/weaviate/pull/12537" target="_blank" rel="noopener noreferrer" class="">#12537</a>) (since <code>v1.39.1</code>)</li>
<li class=""><a href="https://github.com/bharadwaj-pendyala" target="_blank" rel="noopener noreferrer" class="">@bharadwaj-pendyala</a>: excluding LSM scratch files from the <code>offload-s3</code> shard upload (<a href="https://github.com/weaviate/weaviate/pull/12884" target="_blank" rel="noopener noreferrer" class="">#12884</a>)</li>
<li class=""><a href="https://github.com/ColtonRobak" target="_blank" rel="noopener noreferrer" class="">@ColtonRobak</a>: passing the tenant to the re-vectorize check on <code>PATCH</code> (<a href="https://github.com/weaviate/weaviate/pull/13345" target="_blank" rel="noopener noreferrer" class="">#13345</a>) (since <code>v1.39.8</code>)</li>
</ul>
<p>If you'd like to contribute, check out the <a href="https://docs.weaviate.io/contributor-guide/" target="_blank" rel="noopener noreferrer" class="">contributor guide</a> and the <a href="https://github.com/weaviate/weaviate/issues" target="_blank" rel="noopener noreferrer" class=""><code>good-first-issue</code></a> label on GitHub.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="summary">Summary<a href="#summary" class="hash-link" aria-label="Direct link to Summary" title="Direct link to Summary" translate="no">​</a></h2>
<p>Weaviate <code>v1.40</code> promotes two features to general availability, brings multi-vector embeddings to HFresh, and adds a third HNSW filter strategy.</p>
<p><strong>Key highlights:</strong></p>
<ul>
<li class=""><strong>Drop a named vector (GA)</strong>: remove a vector you no longer need from every object, in the background, without re-creating the collection</li>
<li class=""><strong>4-bit Rotational Quantization (GA)</strong>: close to half the memory of 8-bit RQ on HNSW indexes, with optional centering to keep recall high</li>
<li class=""><strong>Multi-vector embeddings on HFresh with MUVERA</strong>: ColBERT and ColPali style embeddings on the disk-based index, through MUVERA encoding</li>
<li class=""><strong>PathSeer filter strategy</strong>: a third way to walk the HNSW graph under a filter, from a SIGMOD 2026 paper, switchable on existing collections</li>
<li class=""><strong>Search REST API (Preview)</strong>: on by default, structured references, and a <code>near-vector</code> endpoint, all since the 1.39 patch line</li>
<li class=""><strong>Vector configuration defaults (breaking change)</strong>: <code>DEFAULT_VECTORIZER_MODULE</code> is ignored, so name your vectorizer in every collection definition before you upgrade</li>
</ul>
<p><strong>Ready to get started?</strong></p>
<p>The release is available open-source on <a href="https://github.com/weaviate/weaviate/releases/tag/v1.40.0" target="_blank" rel="noopener noreferrer" class="">GitHub</a> and on <a href="https://console.weaviate.cloud/" target="_blank" rel="noopener noreferrer" class="">Weaviate Cloud</a>, where you can spin up a cluster on the free tier.</p>
<div class="theme-admonition theme-admonition-note admonition_xJq3 alert alert--secondary"><div class="admonitionHeading_Gvgb"><span class="admonitionIcon_Rf37"><svg viewBox="0 0 14 16"><path fill-rule="evenodd" d="M6.3 5.69a.942.942 0 0 1-.28-.7c0-.28.09-.52.28-.7.19-.18.42-.28.7-.28.28 0 .52.09.7.28.18.19.28.42.28.7 0 .28-.09.52-.28.7a1 1 0 0 1-.7.3c-.28 0-.52-.11-.7-.3zM8 7.99c-.02-.25-.11-.48-.31-.69-.2-.19-.42-.3-.69-.31H6c-.27.02-.48.13-.69.31-.2.2-.3.44-.31.69h1v3c.02.27.11.5.31.69.2.2.42.31.69.31h1c.27 0 .48-.11.69-.31.2-.19.3-.42.31-.69H8V7.98v.01zM7 2.3c-3.14 0-5.7 2.54-5.7 5.68 0 3.14 2.56 5.7 5.7 5.7s5.7-2.55 5.7-5.7c0-3.15-2.56-5.69-5.7-5.69v.01zM7 .98c3.86 0 7 3.14 7 7s-3.14 7-7 7-7-3.12-7-7 3.14-7 7-7z"></path></svg></span>note</div><div class="admonitionContent_BuS1"><p>Not all features may be available on Weaviate Cloud. Preview and experimental features, and anything that needs specific environment configuration, may not be enabled on managed clusters, or may arrive there on a different schedule.</p></div></div>
<p>If you are upgrading a self-hosted cluster, check the <a href="https://docs.weaviate.io/deploy/migration#general-upgrade-instructions" target="_blank" rel="noopener noreferrer" class="">migration guide</a> for version-specific notes.</p>
<p>Thanks for reading, and happy vector searching!</p>
<!-- -->
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="ready-to-start-building">Ready to start building?<a href="#ready-to-start-building" class="hash-link" aria-label="Direct link to Ready to start building?" title="Direct link to Ready to start building?" translate="no">​</a></h2>
<p>Check out the <a href="https://docs.weaviate.io/weaviate/quickstart" target="_blank" rel="noopener noreferrer" class="">Quickstart tutorial</a>, or <a href="https://console.weaviate.cloud/?utm_source=blog&amp;utm_medium=website&amp;utm_campaign=blog_signup&amp;utm_content=weaviate-1-40-release&amp;utm_term=ready-to-start-building" target="_blank" rel="noopener noreferrer">sign up for a free Weaviate Cloud account</a>.</p>
<!-- -->
]]></content:encoded>
            <category>release</category>
            <category>engineering</category>
        </item>
        <item>
            <title><![CDATA[Deprecating the GraphQL API: timeline and migration paths]]></title>
            <link>https://weaviate.io/blog/graphql-api-deprecation</link>
            <guid>https://weaviate.io/blog/graphql-api-deprecation</guid>
            <pubDate>Mon, 26 Oct 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[Weaviate's GraphQL API is deprecated as of October 26, 2026. See the timeline for Weaviate Cloud and self-hosted, who is affected, and how to migrate.]]></description>
            <content:encoded><![CDATA[<p><img decoding="async" loading="lazy" alt="Deprecating the GraphQL API: timeline and migration paths" src="/assets/images/hero-c342f4b670fb3ca24e2f02824fc35a54.jpeg" width="2752" height="1536" class="img_ev3q"></p>
<p>GraphQL was Weaviate's <a class="" href="/blog/graphql-api-design">first query API</a>, and many of you have built on it since our earliest releases. Today we are deprecating it. <strong>Nothing breaks today. Clusters that use GraphQL keep it until May 1, 2027</strong>, the end-of-life date for GraphQL on Weaviate Cloud. We can help you through the migration. Contact our support team through the <a href="https://support.weaviate.io/" target="_blank" rel="noopener noreferrer" class="">support portal</a> or at <a href="mailto:support@weaviate.io" target="_blank" rel="noopener noreferrer" class="">support@weaviate.io</a>, whatever your setup looks like. The <a href="https://docs.weaviate.io/weaviate/api/graphql/migration" target="_blank" rel="noopener noreferrer" class="">GraphQL migration guide</a> walks you through the move, and this post explains why, what happens when, and what your options are.</p>
<div class="theme-admonition theme-admonition-info admonition_xJq3 alert alert--info"><div class="admonitionHeading_Gvgb"><span class="admonitionIcon_Rf37"><svg viewBox="0 0 14 16"><path fill-rule="evenodd" d="M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"></path></svg></span>In short</div><div class="admonitionContent_BuS1"><ul>
<li class="">The GraphQL API is deprecated as of October 26, 2026. Nothing breaks on that day.</li>
<li class="">Weaviate Cloud switches GraphQL off on all clusters on May 1, 2027. May 1, 2027 is the end-of-life date for GraphQL on Weaviate Cloud. If your cluster has not used GraphQL in the last 30 days, it is switched off on December 1, 2026. New Weaviate Cloud clusters are already created without GraphQL.</li>
<li class="">We are emailing all Weaviate Cloud customers so you know whether your clusters are affected.</li>
<li class="">If you are on Weaviate Cloud and need help, contact support through the <a href="https://support.weaviate.io/" target="_blank" rel="noopener noreferrer" class="">support portal</a> or at <a href="mailto:support@weaviate.io" target="_blank" rel="noopener noreferrer" class="">support@weaviate.io</a>.</li>
<li class="">Every Weaviate version released before May 1, 2027 keeps a working GraphQL API. The first minor release after that date disables it by default, and you can switch it back on. It is removed in a later release.</li>
<li class="">If your application searches through a current Python, TypeScript, Java or C# client, you are most likely not affected. Everyone else should follow the <a href="https://docs.weaviate.io/weaviate/api/graphql/migration" target="_blank" rel="noopener noreferrer" class="">migration guide</a>.</li>
</ul></div></div>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="modernizing-weaviates-query-api">Modernizing Weaviate's query API<a href="#modernizing-weaviates-query-api" class="hash-link" aria-label="Direct link to Modernizing Weaviate's query API" title="Direct link to Modernizing Weaviate's query API" translate="no">​</a></h2>
<p>GraphQL served Weaviate and its users well for a long time. It gave you one readable language for every kind of search, and a lot of what you built on Weaviate went through it. We are proud of that work. We are moving to one modern query API, and here is what you gain:</p>
<ul>
<li class="">
<p><strong>Speed:</strong> gRPC sends binary Protocol Buffers over HTTP/2, so queries use less bandwidth and return faster than JSON over HTTP. The <a class="" href="/blog/grpc-performance-improvements">gRPC performance post</a> has the measurements.</p>
</li>
<li class="">
<p><strong>Clear contracts:</strong> Typed messages give every client typed results and generated request objects, so there is no query string to assemble and no nested JSON to parse. Errors arrive as real status codes, not as HTTP <code>200</code> with an <code>errors</code> array. Metadata is a field on the result, not a separate <code>_additional</code> block.</p>
</li>
<li class="">
<p><strong>Security that fits fine-grained access:</strong> GraphQL introspection needs read permission on every collection. That does not fit role-based access control (RBAC) with per-collection permissions. The gRPC and REST APIs check exactly the collection you query.</p>
</li>
<li class="">
<p><strong>Built for how queries are written today:</strong> GraphQL's strength was a query language you could read and type by hand. Today most queries are built by client libraries, frameworks and agents. A compact binary protocol and a plain JSON API serve them better than a hand-written query language.</p>
</li>
<li class="">
<p><strong>Scales to many collections:</strong> A Weaviate instance with many collections is a use case we see more and more often. However, if you have a large number of collections (e.g. 1000+), each addition or removal of a collection may take a significant amount of time as it requires a rebuild of the full GraphQL schema. Retiring GraphQL eliminates this bottleneck.</p>
</li>
</ul>
<p>One API also means every search feature is built, tested and documented once, which lets us ship improvements faster.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="timeline">Timeline<a href="#timeline" class="hash-link" aria-label="Direct link to Timeline" title="Direct link to Timeline" translate="no">​</a></h2>
<p><img decoding="async" loading="lazy" alt="Timeline: September 30, 2026, new Weaviate Cloud clusters are created without GraphQL. October 26, 2026, GraphQL is deprecated and nothing changes in Weaviate Cloud or self-hosted Weaviate. December 1, 2026, GraphQL is switched off on Weaviate Cloud clusters that do not use it. May 1, 2027, GraphQL is switched off on all remaining Cloud clusters. The first minor release after May 1, 2027 disables GraphQL by default in self-hosted Weaviate, where you can switch it back on. A later release fully removes GraphQL from Weaviate." src="/assets/images/timeline-cbb6bd54af2994dcd805793ae9bc21d1.png" width="1942" height="809" class="img_ev3q"></p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="are-you-affected">Are you affected?<a href="#are-you-affected" class="hash-link" aria-label="Direct link to Are you affected?" title="Direct link to Are you affected?" translate="no">​</a></h2>
<p>This only affects you if you send queries to Weaviate over GraphQL. Here is how to tell whether you do.</p>
<p>Your own code sends GraphQL:</p>
<ul>
<li class="">It sends HTTP requests to <code>/v1/graphql</code> directly.</li>
<li class="">It calls a raw GraphQL helper in a client, such as <code>graphql_raw_query()</code> in Python.</li>
<li class="">Browser code in your application posts GraphQL queries.</li>
</ul>
<p>A client or tool sends it for you:</p>
<ul>
<li class="">An older client: the Python v3 API (<code>weaviate.Client</code>), <code>weaviate-ts-client</code> v2, the Java client v5, or the Go client v5 and earlier send queries over GraphQL.</li>
<li class="">A no-code or BI tool that sends GraphQL to your cluster.</li>
</ul>
<p>The guide explains how to <a href="https://docs.weaviate.io/weaviate/api/graphql/migration#find-your-graphql-usage" target="_blank" rel="noopener noreferrer" class="">find your GraphQL usage</a>.</p>
<p>If you reach Weaviate through a framework such as LangChain or LlamaIndex, use the official Weaviate integration built on a current client. A community package may still send GraphQL.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="what-to-use-instead">What to use instead<a href="#what-to-use-instead" class="hash-link" aria-label="Direct link to What to use instead" title="Direct link to What to use instead" translate="no">​</a></h2>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="client-libraries-recommended">Client libraries (recommended)<a href="#client-libraries-recommended" class="hash-link" aria-label="Direct link to Client libraries (recommended)" title="Direct link to Client libraries (recommended)" translate="no">​</a></h3>
<p>The current Python, TypeScript, Java and C# clients search over gRPC, and they are the path we recommend. If you use Go, the move is to the <a href="https://docs.weaviate.io/weaviate/client-libraries/go/go-v6" target="_blank" rel="noopener noreferrer" class="">v6 client</a>, which uses gRPC. See the <a href="https://docs.weaviate.io/weaviate/api/graphql/migration#client-libraries-recommended" target="_blank" rel="noopener noreferrer" class="">client libraries</a> section in the guide.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="typescript-web-client">TypeScript web client<a href="#typescript-web-client" class="hash-link" aria-label="Direct link to TypeScript web client" title="Direct link to TypeScript web client" translate="no">​</a></h3>
<p>For browsers and edge runtimes that cannot open a native gRPC connection, the TypeScript web client (<code>@weaviate/web</code>) uses gRPC-Web. It is available now, with the same API as the Node client. See the <a href="https://docs.weaviate.io/weaviate/api/graphql/migration#typescript-client-for-web" target="_blank" rel="noopener noreferrer" class="">TypeScript client for web</a>.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="rest-search-api">REST Search API<a href="#rest-search-api" class="hash-link" aria-label="Direct link to REST Search API" title="Direct link to REST Search API" translate="no">​</a></h3>
<p>For stacks that cannot run a client at all, the <a href="https://docs.weaviate.io/weaviate/api/graphql/migration#rest-search-api" target="_blank" rel="noopener noreferrer" class="">REST Search API</a> offers plain JSON endpoints for search and aggregation (see the <a href="https://docs.weaviate.io/weaviate/api/rest#tag/search" target="_blank" rel="noopener noreferrer" class="">REST API reference</a>). It is in Preview today. It is a subset of what GraphQL offers, so check the <a href="https://docs.weaviate.io/weaviate/api/graphql/migration#queries-without-a-rest-equivalent-yet" target="_blank" rel="noopener noreferrer" class="">queries without a REST equivalent yet</a> before you start.</p>
<p>A few GraphQL-only features have no equivalent today. The guide lists them under <a href="https://docs.weaviate.io/weaviate/api/graphql/migration#graphql-features-without-an-equivalent" target="_blank" rel="noopener noreferrer" class="">GraphQL features without an equivalent</a>. We are committed to covering what our customers need. If anything you rely on is not covered, reach out to support and we will work on adding it.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="how-to-migrate">How to migrate<a href="#how-to-migrate" class="hash-link" aria-label="Direct link to How to migrate" title="Direct link to How to migrate" translate="no">​</a></h2>
<p>The <a href="https://docs.weaviate.io/weaviate/api/graphql/migration" target="_blank" rel="noopener noreferrer" class="">migration guide</a> maps GraphQL queries to their replacements. There are six months between the deprecation and the end of life on Weaviate Cloud, so you can plan the move around your own releases. And you can switch GraphQL off on your own instance today, so you find out if anything breaks.</p>
<ol>
<li class=""><strong>Find your GraphQL calls:</strong> Search your code, proxies and tools for <code>/v1/graphql</code> and raw GraphQL helpers. See <a href="https://docs.weaviate.io/weaviate/api/graphql/migration#find-your-graphql-usage" target="_blank" rel="noopener noreferrer" class="">find your GraphQL usage</a>.</li>
<li class=""><strong>Pick a path:</strong> Use a client library where you can, the TypeScript web client in the browser, and the REST Search API where neither fits. The guide has a <a href="https://docs.weaviate.io/weaviate/api/graphql/migration#who-this-guide-is-for" target="_blank" rel="noopener noreferrer" class="">decision table</a> for this.</li>
<li class=""><strong>Convert your queries:</strong> Use the <a href="https://docs.weaviate.io/weaviate/api/graphql/migration" target="_blank" rel="noopener noreferrer" class="">Migration guide</a> to map existing GraphQL queries to alternative methods.</li>
<li class=""><strong>Verify with GraphQL disabled:</strong> Run your application against a Weaviate instance with GraphQL turned off. On Weaviate Cloud, contact support and we switch GraphQL off on a cluster of your choice so you can test. See <a href="https://docs.weaviate.io/weaviate/api/graphql/migration#test-with-graphql-disabled" target="_blank" rel="noopener noreferrer" class="">test with GraphQL disabled</a>.</li>
</ol>
<details class="details_lb9f alert alert--info details_b_Ee" data-collapsed="true"><summary>One query, four ways</summary><div><div class="collapsibleContent_i85q"><p>Here is one near-text search on a <code>Movie</code> collection, written four ways: five "space opera" movies from 1980 or later in the <code>scifi</code> category, with title, year and distance.</p><div class="theme-tabs-container tabs-container tabList__CuJ"><ul role="tablist" aria-orientation="horizontal" class="tabs"><li role="tab" tabindex="0" aria-selected="true" class="tabs__item tabItem_LNqP tabs__item--active">GraphQL (deprecated)</li><li role="tab" tabindex="-1" aria-selected="false" class="tabs__item tabItem_LNqP">Python client</li><li role="tab" tabindex="-1" aria-selected="false" class="tabs__item tabItem_LNqP">TypeScript web client</li><li role="tab" tabindex="-1" aria-selected="false" class="tabs__item tabItem_LNqP">REST Search API</li></ul><div class="margin-top--md"><div role="tabpanel" class="tabItem_Ymn6"><div class="language-graphql codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-graphql codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token punctuation" style="color:rgb(248, 248, 242)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">  </span><span class="token object">Get</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    </span><span class="token property-query">Movie</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">      </span><span class="token attr-name" style="color:rgb(241, 250, 140)">nearText</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">{</span><span class="token plain"> </span><span class="token attr-name" style="color:rgb(241, 250, 140)">concepts</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">[</span><span class="token string" style="color:rgb(255, 121, 198)">"space opera"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">]</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">      </span><span class="token attr-name" style="color:rgb(241, 250, 140)">limit</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"> </span><span class="token number">5</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">      </span><span class="token attr-name" style="color:rgb(241, 250, 140)">where</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">        </span><span class="token attr-name" style="color:rgb(241, 250, 140)">operator</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"> </span><span class="token class-name">And</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">        </span><span class="token attr-name" style="color:rgb(241, 250, 140)">operands</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">[</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">          </span><span class="token punctuation" style="color:rgb(248, 248, 242)">{</span><span class="token plain"> </span><span class="token attr-name" style="color:rgb(241, 250, 140)">path</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">[</span><span class="token string" style="color:rgb(255, 121, 198)">"year"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">]</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> </span><span class="token attr-name" style="color:rgb(241, 250, 140)">operator</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"> </span><span class="token class-name">GreaterThanEqual</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> </span><span class="token attr-name" style="color:rgb(241, 250, 140)">valueInt</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"> </span><span class="token number">1980</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">          </span><span class="token punctuation" style="color:rgb(248, 248, 242)">{</span><span class="token plain"> </span><span class="token attr-name" style="color:rgb(241, 250, 140)">path</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">[</span><span class="token string" style="color:rgb(255, 121, 198)">"category"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">]</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> </span><span class="token attr-name" style="color:rgb(241, 250, 140)">operator</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"> </span><span class="token class-name">Equal</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> </span><span class="token attr-name" style="color:rgb(241, 250, 140)">valueText</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"> </span><span class="token string" style="color:rgb(255, 121, 198)">"scifi"</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">        </span><span class="token punctuation" style="color:rgb(248, 248, 242)">]</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">      </span><span class="token punctuation" style="color:rgb(248, 248, 242)">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    </span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">      </span><span class="token property">title</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">      </span><span class="token property">year</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">      </span><span class="token object">_additional</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">        </span><span class="token property">distance</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">      </span><span class="token punctuation" style="color:rgb(248, 248, 242)">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    </span><span class="token punctuation" style="color:rgb(248, 248, 242)">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">  </span><span class="token punctuation" style="color:rgb(248, 248, 242)">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token punctuation" style="color:rgb(248, 248, 242)">}</span><br></span></code></pre></div></div></div><div role="tabpanel" class="tabItem_Ymn6" hidden=""><div class="language-python codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-python codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">from</span><span class="token plain"> weaviate</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">classes</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">query </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">import</span><span class="token plain"> Filter</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> MetadataQuery</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">movies </span><span class="token operator">=</span><span class="token plain"> client</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">collections</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">use</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token string" style="color:rgb(255, 121, 198)">"Movie"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">response </span><span class="token operator">=</span><span class="token plain"> movies</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">query</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">near_text</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    query</span><span class="token operator">=</span><span class="token string" style="color:rgb(255, 121, 198)">"space opera"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    limit</span><span class="token operator">=</span><span class="token number">5</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    filters</span><span class="token operator">=</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">        Filter</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">by_property</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token string" style="color:rgb(255, 121, 198)">"year"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">greater_or_equal</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token number">1980</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">        </span><span class="token operator">&amp;</span><span class="token plain"> Filter</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">by_property</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token string" style="color:rgb(255, 121, 198)">"category"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">equal</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token string" style="color:rgb(255, 121, 198)">"scifi"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    </span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    return_properties</span><span class="token operator">=</span><span class="token punctuation" style="color:rgb(248, 248, 242)">[</span><span class="token string" style="color:rgb(255, 121, 198)">"title"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> </span><span class="token string" style="color:rgb(255, 121, 198)">"year"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">]</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    return_metadata</span><span class="token operator">=</span><span class="token plain">MetadataQuery</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain">distance</span><span class="token operator">=</span><span class="token boolean">True</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">for</span><span class="token plain"> o </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">in</span><span class="token plain"> response</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">objects</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">print</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain">o</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">properties</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> o</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">metadata</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">distance</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><br></span></code></pre></div></div></div><div role="tabpanel" class="tabItem_Ymn6" hidden=""><div class="language-ts codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-ts codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">import</span><span class="token plain"> weaviate</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">{</span><span class="token plain"> Filters </span><span class="token punctuation" style="color:rgb(248, 248, 242)">}</span><span class="token plain"> </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">from</span><span class="token plain"> </span><span class="token string" style="color:rgb(255, 121, 198)">"@weaviate/web"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">const</span><span class="token plain"> client </span><span class="token operator">=</span><span class="token plain"> </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">await</span><span class="token plain"> weaviate</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token function" style="color:rgb(80, 250, 123)">connectToWeaviateCloud</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token constant" style="color:rgb(189, 147, 249)">WEAVIATE_URL</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">  authCredentials</span><span class="token operator">:</span><span class="token plain"> </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">new</span><span class="token plain"> </span><span class="token class-name">weaviate</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token function" style="color:rgb(80, 250, 123)">ApiKey</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token constant" style="color:rgb(189, 147, 249)">WEAVIATE_API_KEY</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token punctuation" style="color:rgb(248, 248, 242)">}</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">const</span><span class="token plain"> movies </span><span class="token operator">=</span><span class="token plain"> client</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">collections</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token function" style="color:rgb(80, 250, 123)">use</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token string" style="color:rgb(255, 121, 198)">"Movie"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">const</span><span class="token plain"> response </span><span class="token operator">=</span><span class="token plain"> </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">await</span><span class="token plain"> movies</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">query</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token function" style="color:rgb(80, 250, 123)">nearText</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token string" style="color:rgb(255, 121, 198)">"space opera"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">  limit</span><span class="token operator">:</span><span class="token plain"> </span><span class="token number">5</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">  filters</span><span class="token operator">:</span><span class="token plain"> Filters</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token function" style="color:rgb(80, 250, 123)">and</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    movies</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">filter</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token function" style="color:rgb(80, 250, 123)">byProperty</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token string" style="color:rgb(255, 121, 198)">"year"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token function" style="color:rgb(80, 250, 123)">greaterOrEqual</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token number">1980</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    movies</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">filter</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token function" style="color:rgb(80, 250, 123)">byProperty</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token string" style="color:rgb(255, 121, 198)">"category"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token function" style="color:rgb(80, 250, 123)">equal</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token string" style="color:rgb(255, 121, 198)">"scifi"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">  </span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">  returnProperties</span><span class="token operator">:</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">[</span><span class="token string" style="color:rgb(255, 121, 198)">"title"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> </span><span class="token string" style="color:rgb(255, 121, 198)">"year"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">]</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">  returnMetadata</span><span class="token operator">:</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">[</span><span class="token string" style="color:rgb(255, 121, 198)">"distance"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">]</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token punctuation" style="color:rgb(248, 248, 242)">}</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">for</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">const</span><span class="token plain"> o </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">of</span><span class="token plain"> response</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">objects</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">  </span><span class="token builtin" style="color:rgb(189, 147, 249)">console</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token function" style="color:rgb(80, 250, 123)">log</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain">o</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">properties</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> o</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">metadata</span><span class="token operator">?.</span><span class="token plain">distance</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token punctuation" style="color:rgb(248, 248, 242)">}</span><br></span></code></pre></div></div></div><div role="tabpanel" class="tabItem_Ymn6" hidden=""><p><code>POST /v1/search/Movie/near-text</code></p><div class="language-json codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-json codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token punctuation" style="color:rgb(248, 248, 242)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">  </span><span class="token property">"query"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">[</span><span class="token string" style="color:rgb(255, 121, 198)">"space opera"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">]</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">  </span><span class="token property">"limit"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token number">5</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">  </span><span class="token property">"where"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    </span><span class="token property">"operator"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:rgb(255, 121, 198)">"And"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    </span><span class="token property">"operands"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">[</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">      </span><span class="token punctuation" style="color:rgb(248, 248, 242)">{</span><span class="token plain"> </span><span class="token property">"path"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">[</span><span class="token string" style="color:rgb(255, 121, 198)">"year"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">]</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> </span><span class="token property">"operator"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:rgb(255, 121, 198)">"GreaterThanEqual"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> </span><span class="token property">"valueInt"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token number">1980</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">}</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">      </span><span class="token punctuation" style="color:rgb(248, 248, 242)">{</span><span class="token plain"> </span><span class="token property">"path"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">[</span><span class="token string" style="color:rgb(255, 121, 198)">"category"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">]</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> </span><span class="token property">"operator"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:rgb(255, 121, 198)">"Equal"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> </span><span class="token property">"valueText"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:rgb(255, 121, 198)">"scifi"</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    </span><span class="token punctuation" style="color:rgb(248, 248, 242)">]</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">  </span><span class="token punctuation" style="color:rgb(248, 248, 242)">}</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">  </span><span class="token property">"returnProperties"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">[</span><span class="token string" style="color:rgb(255, 121, 198)">"title"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> </span><span class="token string" style="color:rgb(255, 121, 198)">"year"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">]</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">  </span><span class="token property">"returnMetadata"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">[</span><span class="token string" style="color:rgb(255, 121, 198)">"distance"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">]</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token punctuation" style="color:rgb(248, 248, 242)">}</span><br></span></code></pre></div></div></div></div></div></div></div></details>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="self-hosted-weaviate">Self-hosted Weaviate<a href="#self-hosted-weaviate" class="hash-link" aria-label="Direct link to Self-hosted Weaviate" title="Direct link to Self-hosted Weaviate" translate="no">​</a></h3>
<p>You can test today. Set the <code>DISABLE_GRAPHQL</code> environment variable to <code>true</code> and restart Weaviate to disable GraphQL. It is also available as the <a href="https://docs.weaviate.io/deploy/configuration/env-vars/runtime-config" target="_blank" rel="noopener noreferrer" class="">runtime-config</a> key <code>disable_graphql</code>.</p>
<p>With GraphQL disabled, <code>POST /v1/graphql</code> and <code>POST /v1/graphql/batch</code> return HTTP <code>422</code>:</p>
<div class="language-json codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-json codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token punctuation" style="color:rgb(248, 248, 242)">{</span><span class="token plain"> </span><span class="token property">"error"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">[</span><span class="token punctuation" style="color:rgb(248, 248, 242)">{</span><span class="token plain"> </span><span class="token property">"message"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:rgb(255, 121, 198)">"graphql api is disabled"</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">}</span><span class="token punctuation" style="color:rgb(248, 248, 242)">]</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">}</span><br></span></code></pre></div></div>
<p>Every Weaviate version released before May 1, 2027 keeps a working GraphQL API. The first minor release after that date disables it by default, and you can switch it back on while you finish migrating. We will remove it in a later release, and we have not set that date yet.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="weaviate-cloud">Weaviate Cloud<a href="#weaviate-cloud" class="hash-link" aria-label="Direct link to Weaviate Cloud" title="Direct link to Weaviate Cloud" translate="no">​</a></h3>
<p>Weaviate Cloud switches GraphQL off in two steps. On December 1, 2026, we switch it off on clusters that have not used GraphQL in the last 30 days, since nothing on them depends on it. On May 1, 2027, we switch it off on all remaining clusters. May 1, 2027 is the end-of-life date for GraphQL on Weaviate Cloud. New clusters are already created without GraphQL.</p>
<p>If your cluster is scheduled for December 1 and you believe it still needs GraphQL, contact support and we switch it off later. If you want to test earlier, support can switch it off on a cluster of your choice.</p>
<p>Once GraphQL is switched off on your cluster, GraphQL requests fail the same way they do with <code>DISABLE_GRAPHQL</code> set: HTTP <code>422</code> with <code>graphql api is disabled</code>. To see how your application behaves before then, test it against a self-hosted instance or a new cluster, which is created without GraphQL.</p>
<p>Weaviate Cloud and Enterprise customers who need help planning the move can contact us through the <a href="https://support.weaviate.io/" target="_blank" rel="noopener noreferrer" class="">support portal</a> or at <a href="mailto:support@weaviate.io" target="_blank" rel="noopener noreferrer" class="">support@weaviate.io</a>.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="get-help">Get help<a href="#get-help" class="hash-link" aria-label="Direct link to Get help" title="Direct link to Get help" translate="no">​</a></h2>
<p>We will get you through this migration. Whatever your setup, and even if you do not know where your GraphQL requests come from, contact support and we work it out with you. If a query or feature you rely on has no equivalent yet, tell us and we will try to add what is missing.</p>
<ul>
<li class=""><strong>Support, for everyone:</strong> Reach our support team through the <a href="https://support.weaviate.io/" target="_blank" rel="noopener noreferrer" class="">support portal</a> or at <a href="mailto:support@weaviate.io" target="_blank" rel="noopener noreferrer" class="">support@weaviate.io</a>.</li>
<li class=""><strong>Community questions:</strong> Ask on the <a href="https://forum.weaviate.io/t/graphql-api-deprecation-timeline-and-how-to-migrate/22669" target="_blank" rel="noopener noreferrer" class="">Weaviate forum</a>.</li>
</ul>
<!-- -->
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="ready-to-start-building">Ready to start building?<a href="#ready-to-start-building" class="hash-link" aria-label="Direct link to Ready to start building?" title="Direct link to Ready to start building?" translate="no">​</a></h2>
<p>Check out the <a href="https://docs.weaviate.io/weaviate/quickstart" target="_blank" rel="noopener noreferrer" class="">Quickstart tutorial</a>, or <a href="https://console.weaviate.cloud/?utm_source=blog&amp;utm_medium=website&amp;utm_campaign=blog_signup&amp;utm_content=graphql-api-deprecation&amp;utm_term=ready-to-start-building" target="_blank" rel="noopener noreferrer">sign up for a free Weaviate Cloud account</a>.</p>
<!-- -->
]]></content:encoded>
            <category>engineering</category>
        </item>
        <item>
            <title><![CDATA[How Weaviate responded to the eMudhra certificate compromise]]></title>
            <link>https://weaviate.io/blog/weaviate-emudhra-response</link>
            <guid>https://weaviate.io/blog/weaviate-emudhra-response</guid>
            <pubDate>Thu, 22 Oct 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[Weaviate patched its entire customer estate and infrastructure platform in under 17 hours to mitigate the risk of eight leaked certificates from the eMudhra certificate authority.]]></description>
            <content:encoded><![CDATA[<p><img decoding="async" loading="lazy" alt="Intro" src="/assets/images/hero-e61bdeeac67f5334bebf1225a7e5b869.jpg" width="1200" height="630" class="img_ev3q"></p>
<p>Yesterday, the engineering team at Weaviate patched our entire customer estate and infrastructure platform to mitigate the risk of eight leaked certificates from the certificate authority eMudhra. While the end-to-end process took us less than 17 hours, and our Enterprise customers were patched within six hours, that's only half of the story.</p>
<p>What was particularly amazing about yesterday's patching effort was that a task force of colleagues from all our engineering teams (our core developers, console, platform and agents teams) and our product support function came together to co-ordinate rolling almost every byte of our environment to Go version 1.27.3. As one team, we created and reviewed pull requests, pushed tags, watched promotions and saw the tests of our services pass.</p>
<p>The security and reliability of our database is paramount to us, and we understand that it is this foundation upon which all of our customer trust is built. It is inspiring watching the Weaviate engineering team at work; from our applied research team who live on the bleeding edge of what is possible with AI, to our platform engineers who manage complex compute, security, observability and deployment infrastructure across three cloud providers, and everyone in between.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="reporting-security-issues">Reporting Security Issues<a href="#reporting-security-issues" class="hash-link" aria-label="Direct link to Reporting Security Issues" title="Direct link to Reporting Security Issues" translate="no">​</a></h2>
<p>If you think you have found a security vulnerability, please go to our <a href="https://weaviate.io/security-report" target="_blank" rel="noopener noreferrer" class="">Security Report page</a> to learn how to send us a report. Weaviate will contact you to acknowledge your report, and advise on next steps. We ask that researchers do not disclose vulnerabilities publicly until they have been fixed and announced, unless you have received a response from the Weaviate security team that you can do so.</p>
<!-- -->
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="ready-to-start-building">Ready to start building?<a href="#ready-to-start-building" class="hash-link" aria-label="Direct link to Ready to start building?" title="Direct link to Ready to start building?" translate="no">​</a></h2>
<p>Check out the <a href="https://docs.weaviate.io/weaviate/quickstart" target="_blank" rel="noopener noreferrer" class="">Quickstart tutorial</a>, or <a href="https://console.weaviate.cloud/?utm_source=blog&amp;utm_medium=website&amp;utm_campaign=blog_signup&amp;utm_content=weaviate-emudhra-response&amp;utm_term=ready-to-start-building" target="_blank" rel="noopener noreferrer">sign up for a free Weaviate Cloud account</a>.</p>
<!-- -->
]]></content:encoded>
            <category>security</category>
        </item>
        <item>
            <title><![CDATA[Weaviate security release - Medium severity fix for a cross-collection vector disclosure in nearObject (CVE pending assignment)]]></title>
            <link>https://weaviate.io/blog/weaviate-security-release-nearobject-2026</link>
            <guid>https://weaviate.io/blog/weaviate-security-release-nearobject-2026</guid>
            <pubDate>Thu, 15 Oct 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[Weaviate v1.39.3 fixes a medium-severity authorization issue in the nearObject GraphQL operator.]]></description>
            <content:encoded><![CDATA[<p><img decoding="async" loading="lazy" alt="Intro" src="/assets/images/hero-e61bdeeac67f5334bebf1225a7e5b869.jpg" width="1200" height="630" class="img_ev3q"></p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="intro">Intro<a href="#intro" class="hash-link" aria-label="Direct link to Intro" title="Direct link to Intro" translate="no">​</a></h2>
<p>With the release of Weaviate <code>v1.39.3</code> and &gt;, there is a fix for a medium severity authorization vulnerability in Weaviate's GraphQL <code>nearObject</code> search operator, where a user could read the vector of an object in a collection they do not have permission to read. A CVE has been requested from MITRE and is pending assignment; we will update this post with the CVE ID once it has been issued.</p>
<p>As per our security policy, Weaviate customers running in Weaviate Cloud, and Marketplace customers on AWS, Azure and GCP have been patched seamlessly. Our Weaviate Enterprise Support customers have received early notification under embargo, and our customer-facing teams are working with Weaviate Dedicated customers to organize version upgrades where appropriate.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="cross-collection-vector-disclosure-via-nearobject-cve-pending-assignment">Cross-collection vector disclosure via nearObject (CVE pending assignment)<a href="#cross-collection-vector-disclosure-via-nearobject-cve-pending-assignment" class="hash-link" aria-label="Direct link to Cross-collection vector disclosure via nearObject (CVE pending assignment)" title="Direct link to Cross-collection vector disclosure via nearObject (CVE pending assignment)" translate="no">​</a></h2>
<p>A <code>nearObject</code> search takes a beacon naming an existing object, loads that object's vector, and uses it as the search vector. Weaviate authorized the collection being searched, but did not authorize the collection named in the beacon. Where the two differed, the vector of the beacon target was loaded and used even if the caller had no read permission on it.</p>
<p>The result is not a direct read of the protected object. The caller never sees the object, its properties or its vector in the response. What the caller does receive is the distance between the protected vector and each object returned by the search, and those distances are enough to reconstruct the protected vector. By populating a collection they do control with chosen probe vectors and then running a <code>nearObject</code> search against that collection with a beacon pointing into a collection they do not control, a caller can recover the protected vector to a high degree of precision. The reporter demonstrated recovery of a normalized four-dimensional vector to within 5e-9 using eight probe objects.</p>
<p>To carry out the attack, a user needs:</p>
<ol>
<li class="">The name of the target collection and the UUID of a specific object within it. These are not guessable, but they are often known, for example where an application stores cross-references between collections.</li>
<li class="">Permission to read collection definitions, which GraphQL requires in order to expose the collection's fields.</li>
<li class="">Permission to create and read data in some other collection, used to hold the probe vectors.</li>
</ol>
<p>The user does not need read permission on the target collection. Weaviate correctly returns 403 for a direct read of the protected object while the same account retrieves the same vector through the search path.</p>
<p>This affects deployments that rely on RBAC to separate collections within a shared cluster, for instance where several teams or applications share one Weaviate instance and each has read access only to its own collection. Deployments where every user with query access is already trusted with all collection data are not meaningfully affected.</p>
<p>The fix authorizes the beacon target before its vector is loaded, at the shared vector lookup rather than in the GraphQL resolver, so that every API surface using that lookup is covered by the same check.</p>
<p>The CVSS score for this vulnerability is Medium.</p>
<p>Impacted versions of Weaviate are &lt; <code>v1.39.3</code>. We recommend that impacted users update their Weaviate installations to <code>v1.39.3</code> or later to fully address the vulnerability. Until you can upgrade, we recommend reviewing which roles hold <code>read_collections</code> across all collections, since a user who cannot see a collection's definition cannot query its fields through GraphQL, and narrowing that permission to the collections each role legitimately needs. Reviewing which roles hold <code>create_data</code> on any collection is also worthwhile, as the attack requires somewhere to place probe vectors.</p>
<p>We have no indication that this vulnerability has been exploited.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="acknowledgements">Acknowledgements<a href="#acknowledgements" class="hash-link" aria-label="Direct link to Acknowledgements" title="Direct link to Acknowledgements" translate="no">​</a></h2>
<p>This vulnerability was discovered and reported by Civitasmass, who notified us through our Vulnerability Disclosure Program. The report included a complete working reproducer and a precise root cause analysis, which allowed us to confirm and fix the issue quickly. We would like to thank them for reporting it responsibly.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="reporting-security-issues">Reporting Security Issues<a href="#reporting-security-issues" class="hash-link" aria-label="Direct link to Reporting Security Issues" title="Direct link to Reporting Security Issues" translate="no">​</a></h2>
<p>If you think you have found a security vulnerability, please go to our <a href="https://weaviate.io/security-report" target="_blank" rel="noopener noreferrer" class="">Security Report page</a> to learn how to send us a report. Weaviate will contact you to acknowledge your report, and advise on next steps. We ask that researchers do not disclose vulnerabilities publicly until they have been fixed and announced, unless you have received a response from the Weaviate security team that you can do so.</p>
<!-- -->
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="ready-to-start-building">Ready to start building?<a href="#ready-to-start-building" class="hash-link" aria-label="Direct link to Ready to start building?" title="Direct link to Ready to start building?" translate="no">​</a></h2>
<p>Check out the <a href="https://docs.weaviate.io/weaviate/quickstart" target="_blank" rel="noopener noreferrer" class="">Quickstart tutorial</a>, or <a href="https://console.weaviate.cloud/?utm_source=blog&amp;utm_medium=website&amp;utm_campaign=blog_signup&amp;utm_content=weaviate-security-release-nearobject-2026&amp;utm_term=ready-to-start-building" target="_blank" rel="noopener noreferrer">sign up for a free Weaviate Cloud account</a>.</p>
<!-- -->
]]></content:encoded>
            <category>security</category>
        </item>
        <item>
            <title><![CDATA[PathSeer: Adaptive Filtered Vector Search]]></title>
            <link>https://weaviate.io/blog/pathseer-filtered-vector-search</link>
            <guid>https://weaviate.io/blog/pathseer-filtered-vector-search</guid>
            <pubDate>Wed, 14 Oct 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[Weaviate 1.40 adds PathSeer, a third HNSW filter strategy from a SIGMOD 2026 paper, contributed by the paper's first author. How it works, and how it compares to sweeping and ACORN.]]></description>
            <content:encoded><![CDATA[<p><img decoding="async" loading="lazy" alt="PathSeer: adaptive filtered vector search" src="/assets/images/hero-0263a6d5e4ea6da32b3ed06b88037bb2.png" width="1200" height="630" class="img_ev3q"></p>
<br>
<!-- -->
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="introduction">Introduction<a href="#introduction" class="hash-link" aria-label="Direct link to Introduction" title="Direct link to Introduction" translate="no">​</a></h2>
<p>Most vector search use-cases have need for filtered vector search and it can be argued this is the most popular query type. A filtered vector search combines a semantic query such as <code>books about architecture</code> with structured criteria like <code>published_date &gt; 2000</code> or <code>language = 'en'</code>.</p>
<p>There are many ways to approach this problem with vector indices. One set of approaches are filter <em><strong>aware</strong></em>, you define what filters will be used upfront. Filter aware approaches perform very well on low-cardinality static data, but do not work well in a dynamic environment where filters (and even the schema) change over time. The other set of approaches (like ACORN) can be termed filter (or predicate) <em><strong>agnostic</strong></em>, and generally amount to different ways to explore the ANN neighbour graph.</p>
<p>In late 2024, we were one of the first vector databases to ship <a class="" href="/blog/speed-up-filtered-vector-search">ACORN</a> as an HNSW filter strategy, and it became the default in 1.34. ACORN performs particularly well when filters are negatively correlated, however it loses recall on very sparse filters, and above 40% selectivity its two-hop expansion costs more than it saves, so we restricted ACORN based on selectivity.</p>
<p>We felt there were still improvements available and so were pleasantly surprised when Zhiyue Li, Guangyan Zhang and colleagues at Tsinghua University announced their SIGMOD 2026 paper <a href="https://doi.org/10.1145/3802098" target="_blank" rel="noopener noreferrer" class=""><em>PathSeer: Adaptive Neighbor Handling for Efficient Filtered ANN Search</em></a>. The paper describes PathSeer, a new predicate-agnostic filtered vector search algorithm in HNSW with large performance improvements over other strategies.</p>
<p>As part of their research, Zhiyue Li added <a href="https://github.com/weaviate/weaviate/pull/12137" target="_blank" rel="noopener noreferrer" class="">PathSeer to Weaviate</a>. In this blog we will go through the algorithm and showcase performance improvements, and how to use it in Weaviate 1.40.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="how-to-handle-a-neighbor">How to handle a neighbor<a href="#how-to-handle-a-neighbor" class="hash-link" aria-label="Direct link to How to handle a neighbor" title="Direct link to How to handle a neighbor" translate="no">​</a></h2>
<p>When using graph-based ANN techniques like HNSW, candidates are found using a beam search algorithm which determines the order in which new nodes get explored.</p>
<p>With unfiltered vector search this is relatively easy - just compute the distance calculation between the query vector and candidate vector. However with filtered vector search there are more decisions to make.</p>
<p>One important decision is: do you compute the distance first or check the filter first?</p>
<p>The PathSeer paper names these two options:</p>
<ul>
<li class=""><strong>Distance first (DFN).</strong> Compute the distance to every neighbor and push it to the candidate heap. Check the filter when a neighbor is good enough to enter the result set. This is equivalent to Weaviate's <em><strong>sweeping</strong></em> strategy. It ensures the graph never disconnects, but at low selectivity most of the distance computations are wasted on nodes that don't pass the filter.</li>
<li class=""><strong>Filter first (DOS).</strong> Check the filter on every neighbor and only calculate distances for the ones that pass. This is in essence <em><strong>ACORN</strong></em>. It avoids wasted distance calculations but has potential to disconnect the graph leading to lower recall. One insight from ACORN is to use 2-hop neighbors, i.e. check if a neighbor matches the filter or any of its neighbors. It tends to work well in low-selectivity filters but at high selectivity the two hops multiply the number of filter checks needed.</li>
</ul>
<p>The paper measured both strategies on six workloads and found the best choice varied by dataset, depending on how selective a filter was and how expensive the filter check was compared to the distance calculation.</p>
<p>In Weaviate we resolve the filter against the inverted index into a <a class="" href="/blog/weaviate-1-18-release#faster-filtering-with-roaring-bitmaps">roaring bitmap</a> before the vector search starts. This ensures that the filter check is just a bitmap lookup (around 17 ns), regardless of how complex the original filter was. The distance computation will cost roughly 50 - 110 ns dependent on quantization and size of the vector.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="introducing-pathseer">Introducing PathSeer<a href="#introducing-pathseer" class="hash-link" aria-label="Direct link to Introducing PathSeer" title="Direct link to Introducing PathSeer" translate="no">​</a></h2>
<p>PathSeer's answer to this is to decide the strategy per node dynamically.</p>
<p>In the paper PathSeer splits each node's neighbor list in two. The <em>sparse zone</em> has the usual pruned HNSW neighbors and is always explored distance first. The <em>expanding zone</em> has extra, unpruned neighbors sorted by distance. The expanding zone is walked filter first until a predefined budget is passed where it switches to distance first. The result is a mixture of filter first and distance first computations with no per query tuning.</p>
<p>In the authors' Faiss implementation this gave 1.2 to 13.5 times the throughput of plain HNSW, and 1.6 to 10.6 times the throughput of ACORN, at 90% recall@10, for selectivities from 100% down to 0.1%.</p>
<p>Zhiyue Li, one of the authors of the PathSeer paper created the original Weaviate PR, however with <a href="https://github.com/weaviate/weaviate/pull/12137#issuecomment-5231357934" target="_blank" rel="noopener noreferrer" class="">notable</a> improvements to compatibility:</p>
<ul>
<li class="">In the new approach, separate neighbor lists are no longer needed and PathSeer is compatible with normal HNSW indices.</li>
<li class="">This allows for filter strategies to be changed on an existing HNSW index - no rebuild required.</li>
</ul>
<p>In the modified approach there are two phases:</p>
<ol>
<li class=""><strong>Two-hop burst.</strong> While the heap has fewer than <code>ef</code> entries, each popped node also adds its two hop neighbors that match the filter. This operates as the expanding zone, but is taken from the existing graph. It stops once the heap is full, so it does not multiply filter checks for the rest of the search.</li>
<li class=""><strong>Once the heap is full, skip distances between non-matching nodes.</strong> When a popped node does not match the filter, its neighbors that also don't match are skipped, with no distance computed. When the popped node does match, all its neighbors get distances as in sweeping, matching or not. The second half is important: non-matching nodes next to matching ones stay in the search as bridges, so it can still cross regions where nothing matches. Skipped nodes are not marked visited, so another path can still reach them later.</li>
</ol>
<!-- -->
<img src="/assets/images/pathseer-modes-4a3524589e17ba00f5a6dc4d21cdd6aa.png" alt="PathSeer's two phases at layer zero: while the result heap is filling, every neighbour of a popped node gets a distance computation and matching two-hop neighbours are added; once the heap holds ef matches, a popped node that fails the filter skips its non-matching neighbours without a distance computation" class="themedComponent_mlkZ themedComponent--light_NVdE"><img src="/assets/images/pathseer-modes_dark-23e31c65b47086da68943be47e00c89b.png" alt="PathSeer's two phases at layer zero: while the result heap is filling, every neighbour of a popped node gets a distance computation and matching two-hop neighbours are added; once the heap holds ef matches, a popped node that fails the filter skips its non-matching neighbours without a distance computation" class="themedComponent_mlkZ themedComponent--dark_xIcU">
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="benchmarks">Benchmarks<a href="#benchmarks" class="hash-link" aria-label="Direct link to Benchmarks" title="Direct link to Benchmarks" translate="no">​</a></h2>
<p>The below benchmarks used a Weaviate 1.40 build on a GCP c4-standard-16 (16 vCPUs, 60 GB Memory) instance. The Weaviate <a href="https://github.com/weaviate/weaviate-benchmarking" target="_blank" rel="noopener noreferrer" class="">benchmarker</a> tool was used, in particular with flat search cutoff disabled, so we could test the filtered ANN performance even when normally the filter would be restrictive enough to trigger a brute force search.</p>
<p>Three sources for filtered datasets are used.</p>
<ul>
<li class=""><strong>BEIR Cohere.</strong> The sets from the ACORN post: 500k Cohere v3 embeddings mixed from the NQ and MS MARCO corpora, with a filter on the MS MARCO share, plus a 1.1M set of 22 BEIR corpora with a filter on the source corpus.</li>
<li class=""><strong>Sphere DPR.</strong> 1M 768-dimension embeddings with uniformly random categories.</li>
<li class=""><strong>wiki-dpr 10M.</strong> 10M Wiki passages from <a href="https://huggingface.co/datasets/kenhktsui/wiki_dpr_e5" target="_blank" rel="noopener noreferrer" class="">e5-base-v2 embeddings</a> on Hugging Face, with 27 generated filters (random, topical, and conjunction) and exact filtered ground truth for each.</li>
</ul>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="topical-filters">Topical filters<a href="#topical-filters" class="hash-link" aria-label="Direct link to Topical filters" title="Direct link to Topical filters" translate="no">​</a></h3>
<p>First we use a filtered dataset using Cohere v3 embeddings from BEIR that we used previously to evaluate ACORN. We combine two datasets (NQ and MSMARCO) and vary the percentage to change the selectivity of the filter.</p>
<p>In this dataset PathSeer matches or beats both sweeping and ACORN at every selectivity range.</p>
<!-- -->
<img src="/assets/images/qps_at_recall_vs_selectivity-974225d9c7a65c3990af06bd55a9f046.png" alt="Throughput at recall@10 = 0.90 against filter selectivity from 20% to 90% for sweeping, acorn and pathseer on BEIR Cohere 500k" class="themedComponent_mlkZ themedComponent--light_NVdE"><img src="/assets/images/qps_at_recall_vs_selectivity_dark-c291e2e6fad0c81fcfd6a2996543a8b4.png" alt="Throughput at recall@10 = 0.90 against filter selectivity from 20% to 90% for sweeping, acorn and pathseer on BEIR Cohere 500k" class="themedComponent_mlkZ themedComponent--dark_xIcU">
<p>Here is a QPS vs recall graph showing 20% selectivity (20% of the dataset matches the filter) and low correlation (the query vector is not part of the filter).</p>
<!-- -->
<img src="/assets/images/qps_recall_beir-cohere-500k-filtered-dot-0.2-3c62077633dd459274a075e3ea2b123c.png" alt="QPS vs recall@10 for sweeping, acorn and pathseer on BEIR Cohere 500k at 20% selectivity" class="themedComponent_mlkZ themedComponent--light_NVdE"><img src="/assets/images/qps_recall_beir-cohere-500k-filtered-dot-0.2_dark-2d333e2c0f12803555275ed3f12695fd.png" alt="QPS vs recall@10 for sweeping, acorn and pathseer on BEIR Cohere 500k at 20% selectivity" class="themedComponent_mlkZ themedComponent--dark_xIcU">
<p>Next, and importantly, here is a graph showing again at 20% selectivity what happens when the query vector is part of the filter region. This is the scenario where previously sweeping would outperform ACORN, however here PathSeer outperforms both.</p>
<!-- -->
<img src="/assets/images/qps_recall_beir-cohere-500k-filtered-dot-correlated-0.2-1194b9a57a7efd7a449b4cb6d73c6b44.png" alt="QPS vs recall@10 for sweeping, acorn and pathseer on BEIR Cohere 500k at 20% selectivity with a filter correlated to the query" class="themedComponent_mlkZ themedComponent--light_NVdE"><img src="/assets/images/qps_recall_beir-cohere-500k-filtered-dot-correlated-0.2_dark-f7dffaddf28cd88cd130957d44f250dd.png" alt="QPS vs recall@10 for sweeping, acorn and pathseer on BEIR Cohere 500k at 20% selectivity with a filter correlated to the query" class="themedComponent_mlkZ themedComponent--dark_xIcU">
<p>On the wiki-dpr 10M dataset we see PathSeer clearly outperforms ACORN and also exceeds sweeping on topical filters (built here by clustering the article embeddings, so the matching passages form a region of the graph).</p>
<!-- -->
<img src="/assets/images/wiki_qps_at_recall_vs_size_topical-7a2fd02f2d553db0e48420d2a8ff8308.png" alt="Throughput at recall@10 = 0.90 against selectivity from 0.1% to 50% for topical filters on wiki-dpr 10M, for sweeping, acorn and pathseer" class="themedComponent_mlkZ themedComponent--light_NVdE"><img src="/assets/images/wiki_qps_at_recall_vs_size_topical_dark-8ff0f67875e379a18c7446ca943fffc8.png" alt="Throughput at recall@10 = 0.90 against selectivity from 0.1% to 50% for topical filters on wiki-dpr 10M, for sweeping, acorn and pathseer" class="themedComponent_mlkZ themedComponent--dark_xIcU">
<p>Note that at 0.1% selectivity Weaviate would normally switch to a brute force search over the filter set (the default <code>flatSearchCutoff</code> is 40,000 objects), which is the better choice at that size.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="conjunction-filters">Conjunction filters<a href="#conjunction-filters" class="hash-link" aria-label="Direct link to Conjunction filters" title="Direct link to Conjunction filters" translate="no">​</a></h3>
<p>The conjunction filters are the ones closest to a production filter: a semantic attribute combined with a range on something orthogonal, such as a date or a tenant. On wiki-dpr each one is a topical filter AND a range on the object id, which breaks the link between where a passage sits in the embedding space and where it sits in the index. Six of them span 55k to 911k passages.</p>
<!-- -->
<img src="/assets/images/wiki_qps_at_recall_vs_size_conjunction-e5e67f814b9bb1516405ce3617409b63.png" alt="Throughput at recall@10 = 0.90 against selectivity for the six conjunction filters on wiki-dpr 10M, for sweeping, acorn and pathseer" class="themedComponent_mlkZ themedComponent--light_NVdE"><img src="/assets/images/wiki_qps_at_recall_vs_size_conjunction_dark-c935ef312bcd3d5074d2f90a949e5a73.png" alt="Throughput at recall@10 = 0.90 against selectivity for the six conjunction filters on wiki-dpr 10M, for sweeping, acorn and pathseer" class="themedComponent_mlkZ themedComponent--dark_xIcU">
<p>PathSeer is the fastest strategy at 0.90 recall on all six, by 1.1 to 1.4 times over the better of sweeping and ACORN. ACORN reaches 0.90 on only three of them.</p>
<!-- -->
<img src="/assets/images/qps_recall_wiki-global_conj_topical1m_a_idmid-f973ac025ba0a67dc8b5a5833061239c.png" alt="QPS vs recall@10 on wiki-dpr 10M with a conjunction filter of 238k passages (topical AND id range, 2.4% selectivity) for sweeping, acorn and pathseer" class="themedComponent_mlkZ themedComponent--light_NVdE"><img src="/assets/images/qps_recall_wiki-global_conj_topical1m_a_idmid_dark-dc32bca69cd2f15493818661561dd84e.png" alt="QPS vs recall@10 on wiki-dpr 10M with a conjunction filter of 238k passages (topical AND id range, 2.4% selectivity) for sweeping, acorn and pathseer" class="themedComponent_mlkZ themedComponent--dark_xIcU">
<p>On this 238k-passage conjunction PathSeer is 1.36 times sweeping at 0.90 recall and reaches 0.98 at ef 512, while ACORN tops out at 0.86.</p>
<!-- -->
<img src="/assets/images/qps_recall_wiki-global_conj_topical1m_a_idlo-ff3e2bcfe36bb73ca8d93ed65e6a6c4b.png" alt="QPS vs recall@10 on wiki-dpr 10M with a conjunction filter of 532k passages (topical AND id range, 5.3% selectivity) for sweeping, acorn and pathseer" class="themedComponent_mlkZ themedComponent--light_NVdE"><img src="/assets/images/qps_recall_wiki-global_conj_topical1m_a_idlo_dark-37f15358128ac8cd51027ee8986bd761.png" alt="QPS vs recall@10 on wiki-dpr 10M with a conjunction filter of 532k passages (topical AND id range, 5.3% selectivity) for sweeping, acorn and pathseer" class="themedComponent_mlkZ themedComponent--dark_xIcU">
<p>The larger conjunction, 532k passages at 5.3% selectivity, is dense enough for ACORN to reach 0.90 recall, and PathSeer is still ahead of both: 1.3 times sweeping and 1.7 times ACORN at 0.90, with a recall ceiling of 0.98 against ACORN's 0.93.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="random-filters">Random filters<a href="#random-filters" class="hash-link" aria-label="Direct link to Random filters" title="Direct link to Random filters" translate="no">​</a></h3>
<p>Random filters are where the filter has zero correlation with the query. They are the easiest test datasets to generate (just randomly assign each vector to a cluster based on the desired selectivity).</p>
<p>Here the filter carries no semantic information, so we can't deliberately move to a region with more vectors passing the filter, which most exposes ACORN. In these examples we see PathSeer degrade to sweeping, with an improvement at very low selectivity.</p>
<!-- -->
<img src="/assets/images/wiki_qps_at_recall_vs_size_random-5ebc36a2d557dd91ddb209420df69c6d.png" alt="Throughput at recall@10 = 0.90 against selectivity from 0.1% to 50% for uniformly random filters on wiki-dpr 10M, for sweeping, acorn and pathseer" class="themedComponent_mlkZ themedComponent--light_NVdE"><img src="/assets/images/wiki_qps_at_recall_vs_size_random_dark-5154d4c80e58048aff9a31d70ed5e945.png" alt="Throughput at recall@10 = 0.90 against selectivity from 0.1% to 50% for uniformly random filters on wiki-dpr 10M, for sweeping, acorn and pathseer" class="themedComponent_mlkZ themedComponent--dark_xIcU">
<!-- -->
<img src="/assets/images/qps_recall_wiki-global_random_400k-6201ef85500612ac0691ec7534fe95bb.png" alt="QPS vs recall@10 on wiki-dpr 10M with a uniform random filter of 400k passages (4% selectivity) for sweeping, acorn and pathseer" class="themedComponent_mlkZ themedComponent--light_NVdE"><img src="/assets/images/qps_recall_wiki-global_random_400k_dark-dfd1e1040b2a11da797e4f1a32b69b93.png" alt="QPS vs recall@10 on wiki-dpr 10M with a uniform random filter of 400k passages (4% selectivity) for sweeping, acorn and pathseer" class="themedComponent_mlkZ themedComponent--dark_xIcU">
<!-- -->
<img src="/assets/images/qps_recall_sphere-1M-meta-dpr-dot-filtered-uniform20-0caa6952659b8ab409f395af4b4da810.png" alt="QPS vs recall@10 for sweeping, acorn and pathseer on Sphere DPR 1M with a uniformly random filter at 5% selectivity" class="themedComponent_mlkZ themedComponent--light_NVdE"><img src="/assets/images/qps_recall_sphere-1M-meta-dpr-dot-filtered-uniform20_dark-7aa733154e0b8834973f298d7dc0dd67.png" alt="QPS vs recall@10 for sweeping, acorn and pathseer on Sphere DPR 1M with a uniformly random filter at 5% selectivity" class="themedComponent_mlkZ themedComponent--dark_xIcU">
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="negatively-correlated-filters">Negatively correlated filters<a href="#negatively-correlated-filters" class="hash-link" aria-label="Direct link to Negatively correlated filters" title="Direct link to Negatively correlated filters" translate="no">​</a></h3>
<p>Finally the most difficult case is where the query is strongly negatively correlated with the filter. In this case, the distance calculations point the beam search in the wrong direction (towards better ANN results but fewer filter matches) and this has historically been a major reason for recommending ACORN.</p>
<p>Here we see ACORN still heavily outperforming sweeping, and also outperforming PathSeer, though by a much smaller margin.</p>
<!-- -->
<img src="/assets/images/qps_recall_beir-cohere-dot-filtered-negative-7819161e024840997ad0e80302a3e4d6.png" alt="QPS vs recall@10 for sweeping, acorn and pathseer on 1.1M BEIR Cohere vectors with a negatively correlated filter at about 4.5% selectivity" class="themedComponent_mlkZ themedComponent--light_NVdE"><img src="/assets/images/qps_recall_beir-cohere-dot-filtered-negative_dark-4636118695a1411a50228ad5de847cf2.png" alt="QPS vs recall@10 for sweeping, acorn and pathseer on 1.1M BEIR Cohere vectors with a negatively correlated filter at about 4.5% selectivity" class="themedComponent_mlkZ themedComponent--dark_xIcU">
<p>One property PathSeer keeps from sweeping is that recall continues to climb with <code>ef</code>. At ef 2048 PathSeer reaches 0.998 recall on this dataset while ACORN plateaus at 0.984, so for very high recall targets on a filter like this PathSeer is the graph strategy that gets there.</p>
<p>To put a number on "correlated", we measured for each dataset what share of a query's unfiltered top-10 neighbors pass the filter, divided by the filter's selectivity. A value of 1 means the filter is independent of the query, above 1 the filter favors the query's neighborhood, and below 1 it excludes it.</p>
<table><thead><tr><th>Dataset</th><th>Filter</th><th>Selectivity</th><th>Correlation</th><th>Fastest at 0.90 recall</th></tr></thead><tbody><tr><td>BEIR Cohere 1.1M</td><td>query's own corpus</td><td>5.5%</td><td>16.4</td><td>pathseer (acorn within 1%)</td></tr><tr><td>wiki-dpr 10M</td><td>conjunction</td><td>0.5% to 9%</td><td>0.7 to 3.7</td><td>pathseer, all six filters</td></tr><tr><td>wiki-dpr 10M</td><td>random</td><td>0.1% to 50%</td><td>1.0</td><td>pathseer and sweeping within 7%</td></tr><tr><td>wiki-dpr 10M</td><td>topical</td><td>0.1% to 50%</td><td>0.3 to 1.2</td><td>pathseer, 1.0 to 1.4x sweeping</td></tr><tr><td>BEIR Cohere 500k</td><td>MS MARCO share, NQ queries</td><td>20%</td><td>0.5</td><td>pathseer, 1.24x acorn</td></tr><tr><td>BEIR Cohere 1.1M</td><td>a different corpus than the query</td><td>4.5%</td><td>0.07</td><td>acorn, 8.7x pathseer</td></tr></tbody></table>
<p>The wiki-dpr topical and random filters sit close to 1: the matching passages are simply sparse, not pushed away from the query. PathSeer is the fastest strategy at every correlation down to 0.5, and ACORN takes over only when the filter all but excludes the query's neighborhood.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="summary">Summary<a href="#summary" class="hash-link" aria-label="Direct link to Summary" title="Direct link to Summary" translate="no">​</a></h3>
<p>Queries per second at recall@10 = 0.90, interpolated between the two nearest ef points. "n/a" means the strategy did not reach 0.90 recall at any ef up to 512. wiki-dpr topical rows are the mean of the two variants.</p>
<table><thead><tr><th>Filter</th><th>Dataset</th><th>sweeping</th><th>acorn</th><th>pathseer</th><th>pathseer vs best of sweeping, acorn</th></tr></thead><tbody><tr><td>random</td><td>Sphere DPR 1M, 5% selectivity</td><td>2509</td><td>1144</td><td>3464</td><td>1.38x</td></tr><tr><td>random</td><td>Sphere DPR 1M, 1% selectivity</td><td>689</td><td>n/a</td><td>1193</td><td>1.73x</td></tr><tr><td>random</td><td>wiki-dpr 10M, 0.1% (10k)</td><td>117</td><td>n/a</td><td>176</td><td>1.50x</td></tr><tr><td>random</td><td>wiki-dpr 10M, 1% (100k)</td><td>597</td><td>n/a</td><td>558</td><td>0.93x</td></tr><tr><td>random</td><td>wiki-dpr 10M, 4% (400k)</td><td>983</td><td>376</td><td>1047</td><td>1.07x</td></tr><tr><td>random</td><td>wiki-dpr 10M, 10% (1M)</td><td>1236</td><td>765</td><td>1223</td><td>0.99x</td></tr><tr><td>random</td><td>wiki-dpr 10M, 50% (5M)</td><td>1562</td><td>1552</td><td>1516</td><td>0.97x</td></tr><tr><td>topical</td><td>BEIR Cohere 500k, 20% selectivity, low correlation</td><td>1700</td><td>5626</td><td>6996</td><td>1.24x</td></tr><tr><td>topical</td><td>BEIR Cohere 500k, 30% selectivity, low correlation</td><td>2423</td><td>5167</td><td>6668</td><td>1.29x</td></tr><tr><td>topical</td><td>BEIR Cohere 500k, 40% selectivity, low correlation</td><td>2681</td><td>2707</td><td>6996</td><td>2.58x</td></tr><tr><td>topical</td><td>BEIR Cohere 500k, 50% selectivity, low correlation</td><td>3893</td><td>3948</td><td>7404</td><td>1.88x</td></tr><tr><td>topical</td><td>BEIR Cohere 500k, 70% selectivity, low correlation</td><td>9825</td><td>9774</td><td>10050</td><td>1.02x</td></tr><tr><td>topical</td><td>BEIR Cohere 500k, 90% selectivity, low correlation</td><td>10012</td><td>10110</td><td>10147</td><td>1.00x</td></tr><tr><td>topical</td><td>BEIR Cohere 500k, 20% selectivity, high correlation</td><td>7408</td><td>8034</td><td>9521</td><td>1.19x</td></tr><tr><td>topical</td><td>BEIR Cohere 1.1M, ~4.5% selectivity, positive correlation</td><td>8397</td><td>9109</td><td>9214</td><td>1.01x</td></tr><tr><td>topical</td><td>wiki-dpr 10M, 0.1% (10k)</td><td>50</td><td>n/a</td><td>70</td><td>1.40x</td></tr><tr><td>topical</td><td>wiki-dpr 10M, 0.4% (40k)</td><td>108</td><td>n/a</td><td>138</td><td>1.28x</td></tr><tr><td>topical</td><td>wiki-dpr 10M, 1% (100k)</td><td>186</td><td>n/a</td><td>194</td><td>1.04x</td></tr><tr><td>topical</td><td>wiki-dpr 10M, 4% (400k)</td><td>662</td><td>374</td><td>737</td><td>1.11x</td></tr><tr><td>topical</td><td>wiki-dpr 10M, 10% (1M)</td><td>884</td><td>536</td><td>959</td><td>1.08x</td></tr><tr><td>topical</td><td>wiki-dpr 10M, 20% (2M)</td><td>1233</td><td>865</td><td>1195</td><td>0.97x</td></tr><tr><td>topical</td><td>wiki-dpr 10M, 50% (5M)</td><td>1308</td><td>1300</td><td>1323</td><td>1.01x</td></tr><tr><td>conjunction</td><td>wiki-dpr 10M, 2.4% (238k)</td><td>478</td><td>n/a</td><td>649</td><td>1.36x</td></tr><tr><td>conjunction</td><td>wiki-dpr 10M, 5.3% (532k)</td><td>662</td><td>497</td><td>850</td><td>1.28x</td></tr><tr><td>negative</td><td>BEIR Cohere 1.1M, ~4.5% selectivity, negative correlation</td><td>79</td><td>1880</td><td>216</td><td>0.12x</td></tr></tbody></table>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="using-pathseer">Using PathSeer<a href="#using-pathseer" class="hash-link" aria-label="Direct link to Using PathSeer" title="Direct link to Using PathSeer" translate="no">​</a></h2>
<p>PathSeer ships in Weaviate 1.40 as a value of the existing <code>filterStrategy</code> setting on the HNSW index. The default remains <code>acorn</code>.</p>
<div class="language-json codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-json codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token property">"vectorIndexConfig"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">  </span><span class="token property">"filterStrategy"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:rgb(255, 121, 198)">"pathseer"</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token punctuation" style="color:rgb(248, 248, 242)">}</span><br></span></code></pre></div></div>
<p>The setting is mutable, so an existing collection can be switched without reindexing. The <code>flatSearchCutoff</code> setting still applies before any strategy: filters matching fewer objects than the cutoff are brute-forced as before.</p>
<p>With the Python client, set the strategy when creating a collection:</p>
<div class="language-python codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-python codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">from</span><span class="token plain"> weaviate</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">classes</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">config </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">import</span><span class="token plain"> Configure</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> VectorFilterStrategy</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">client</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">collections</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">create</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    </span><span class="token string" style="color:rgb(255, 121, 198)">"Article"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    vector_index_config</span><span class="token operator">=</span><span class="token plain">Configure</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">VectorIndex</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">hnsw</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">        filter_strategy</span><span class="token operator">=</span><span class="token plain">VectorFilterStrategy</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">PATHSEER</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    </span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><br></span></code></pre></div></div>
<p>Or switch an existing collection:</p>
<div class="language-python codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-python codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">from</span><span class="token plain"> weaviate</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">classes</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">config </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">import</span><span class="token plain"> Reconfigure</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> VectorFilterStrategy</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">articles </span><span class="token operator">=</span><span class="token plain"> client</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">collections</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">use</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token string" style="color:rgb(255, 121, 198)">"Article"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">articles</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">config</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">update</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    vector_index_config</span><span class="token operator">=</span><span class="token plain">Reconfigure</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">VectorIndex</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">hnsw</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">        filter_strategy</span><span class="token operator">=</span><span class="token plain">VectorFilterStrategy</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">PATHSEER</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    </span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><br></span></code></pre></div></div>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="conclusion">Conclusion<a href="#conclusion" class="hash-link" aria-label="Direct link to Conclusion" title="Direct link to Conclusion" translate="no">​</a></h2>
<p>PathSeer is the fastest filter strategy in Weaviate on almost every workload we tested, and it holds up where ACORN loses recall and where sweeping loses throughput. It needs no reindexing and no new parameters: set <code>filterStrategy</code> to <code>pathseer</code> on an existing collection and it takes effect immediately. Try it on your own filters in Weaviate 1.40 and let us know how it performs.</p>
<!-- -->
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="ready-to-start-building">Ready to start building?<a href="#ready-to-start-building" class="hash-link" aria-label="Direct link to Ready to start building?" title="Direct link to Ready to start building?" translate="no">​</a></h2>
<p>Check out the <a href="https://docs.weaviate.io/weaviate/quickstart" target="_blank" rel="noopener noreferrer" class="">Quickstart tutorial</a>, or <a href="https://console.weaviate.cloud/?utm_source=blog&amp;utm_medium=website&amp;utm_campaign=blog_signup&amp;utm_content=pathseer-filtered-vector-search&amp;utm_term=ready-to-start-building" target="_blank" rel="noopener noreferrer">sign up for a free Weaviate Cloud account</a>.</p>
<!-- -->
]]></content:encoded>
            <category>engineering</category>
            <category>research</category>
            <category>search</category>
        </item>
        <item>
            <title><![CDATA[Weaviate security release - High severity fix for credential disclosure in the Google modules]]></title>
            <link>https://weaviate.io/blog/weaviate-security-release-googlemodules-2026</link>
            <guid>https://weaviate.io/blog/weaviate-security-release-googlemodules-2026</guid>
            <pubDate>Thu, 01 Oct 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[Weaviate v1.39.3 fixes a high-severity credential disclosure issue in the Google modules.]]></description>
            <content:encoded><![CDATA[<p><img decoding="async" loading="lazy" alt="Intro." src="/assets/images/hero-dca5d7a36cd761ae60076cb3a4332952.png" width="1200" height="630" class="img_ev3q"></p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="intro">Intro<a href="#intro" class="hash-link" aria-label="Direct link to Intro" title="Direct link to Intro" translate="no">​</a></h2>
<p>Weaviate <code>v1.39.3</code> includes a fix for a high severity credential disclosure vulnerability in Weaviate's Google-backed modules, where an unvalidated endpoint setting could be used to redirect an outbound request, and the operator's Google credential with it, to an arbitrary host. A CVE has been requested from MITRE and is pending assignment; we will update this post with the CVE ID once it has been issued.</p>
<p>As per our security policy, Weaviate customers running in Weaviate Cloud, and Marketplace customers on AWS, Azure and GCP have been patched seamlessly. Our Weaviate Enterprise Support customers have received early notification under embargo, and our customer-facing teams are working with Weaviate Dedicated customers to organize version upgrades where appropriate.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="credential-disclosure-via-unvalidated-apiendpoint-in-the-google-modules-cve-pending-assignment">Credential disclosure via unvalidated apiEndpoint in the Google modules (CVE pending assignment)<a href="#credential-disclosure-via-unvalidated-apiendpoint-in-the-google-modules-cve-pending-assignment" class="hash-link" aria-label="Direct link to Credential disclosure via unvalidated apiEndpoint in the Google modules (CVE pending assignment)" title="Direct link to Credential disclosure via unvalidated apiEndpoint in the Google modules (CVE pending assignment)" translate="no">​</a></h2>
<p>Weaviate's Google-backed modules (<code>text2vec-google</code>, <code>multi2vec-google</code> and <code>generative-google</code>) allow the host used for outbound Vertex AI and Gemini requests to be set through an <code>apiEndpoint</code> configuration value. That value was written directly into the host portion of the request URL without validation, and the operator's configured Google credential was attached to the request as a bearer token regardless of where the request was being sent. A user who can influence <code>apiEndpoint</code> could therefore cause Weaviate to deliver that credential to a host of their choosing.</p>
<p>There were two paths to setting the value:</p>
<ol>
<li class="">Through collection configuration. Setting <code>moduleConfig.text2vec-google.apiEndpoint</code> (or the equivalent for the other two modules) when creating or updating a collection. Validation at this layer checked only that a project ID was present; the endpoint string itself was never checked. This path requires schema-write privileges.</li>
<li class="">Through a GraphQL query parameter. <code>generative-google</code> accepted <code>apiEndpoint</code> as an inline parameter on a generative query, and the per-query value overrode the collection default. This path requires only ordinary read access to a collection already configured to use <code>generative-google</code>, with no schema-write privilege and no change to stored configuration.</li>
</ol>
<p>The second path is the more serious of the two, and is the main reason for the severity rating.</p>
<p>The credential exposed depends on how the deployment authenticates to Google. Where a static API key is configured, that key is disclosed. Where <code>USE_GOOGLE_AUTH</code> is enabled, the disclosed value is a live OAuth access token scoped to <code>cloud-platform</code>, which is broad enough to reach most Google Cloud APIs available to the underlying service account. This is the documented way to run Vertex AI vectorization using Google Cloud Application Default Credentials, and the usual arrangement for GKE deployments using Workload Identity.</p>
<p>This is a distinct code path from the base URL validation added in earlier releases. That work hardened the endpoint fields of a large number of other model providers, but those fields are named <code>baseURL</code>; the Google modules' field is named <code>apiEndpoint</code> and was not covered. The related dial-time protection is also opt-in via <code>MODULES_VALIDATE_BASE_URL</code> and blocks only loopback, private and link-local addresses, so it does not prevent a credential being sent to an attacker-controlled host on the public internet.</p>
<p>The fix extends endpoint validation to the <code>apiEndpoint</code> field in all three Google modules, at both the configuration-validation layer and the GraphQL query-parameter layer.</p>
<p>The CVSS score for this vulnerability is High (7.1).</p>
<p>Impacted versions of Weaviate are &lt; <code>v1.39.3</code>. We recommend that impacted users update their Weaviate installations to <code>v1.39.3</code> or later to fully address the vulnerability. Until you can upgrade, the affected modules can be disabled by removing <code>text2vec-google</code>, <code>multi2vec-google</code> and <code>generative-google</code> from the <code>"enabled_modules"</code> flag. Where the modules are required, we recommend restricting schema-write and query access to collections configured to use them, and scoping the service account used for Vertex AI as narrowly as your workload allows rather than relying on a broad <code>cloud-platform</code> scope.</p>
<p>We have no indication that this vulnerability has been exploited.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="acknowledgements">Acknowledgements<a href="#acknowledgements" class="hash-link" aria-label="Direct link to Acknowledgements" title="Direct link to Acknowledgements" translate="no">​</a></h2>
<p>This vulnerability was discovered and reported by Syed Anas Mohiuddin, an independent security researcher, who notified us through our Vulnerability Disclosure Program. We would like to thank him for the detail and care of the report, and for working with us through validation and remediation.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="reporting-security-issues">Reporting Security Issues<a href="#reporting-security-issues" class="hash-link" aria-label="Direct link to Reporting Security Issues" title="Direct link to Reporting Security Issues" translate="no">​</a></h2>
<p>If you think you have found a security vulnerability, please go to our <a href="https://weaviate.io/security-report" target="_blank" rel="noopener noreferrer" class="">Security Report page</a> to learn how to send us a report. Weaviate will contact you to acknowledge your report, and advise on next steps. We ask that researchers do not disclose vulnerabilities publicly until they have been fixed and announced, unless you have received a response from the Weaviate security team that you can do so.</p>
<!-- -->
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="ready-to-start-building">Ready to start building?<a href="#ready-to-start-building" class="hash-link" aria-label="Direct link to Ready to start building?" title="Direct link to Ready to start building?" translate="no">​</a></h2>
<p>Check out the <a href="https://docs.weaviate.io/weaviate/quickstart" target="_blank" rel="noopener noreferrer" class="">Quickstart tutorial</a>, or <a href="https://console.weaviate.cloud/?utm_source=blog&amp;utm_medium=website&amp;utm_campaign=blog_signup&amp;utm_content=weaviate-security-release-googlemodules-2026&amp;utm_term=ready-to-start-building" target="_blank" rel="noopener noreferrer">sign up for a free Weaviate Cloud account</a>.</p>
<!-- -->
]]></content:encoded>
            <category>security</category>
        </item>
        <item>
            <title><![CDATA[4-bit Rotational Quantization]]></title>
            <link>https://weaviate.io/blog/4-bit-rotational-quantization</link>
            <guid>https://weaviate.io/blog/4-bit-rotational-quantization</guid>
            <pubDate>Thu, 17 Sep 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[4-bit Rotational Quantization in Weaviate 1.39: the SIMD performance work, a centered tier, scaling analysis and a TurboQuant comparison.]]></description>
            <content:encoded><![CDATA[<p><img decoding="async" loading="lazy" alt="4-bit rotational quantization" src="/assets/images/hero-d584373a01efba8ebdec29de80ed039f.png" width="1200" height="630" class="img_ev3q"></p>
<br>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="introduction">Introduction<a href="#introduction" class="hash-link" aria-label="Direct link to Introduction" title="Direct link to Introduction" translate="no">​</a></h2>
<p>Last year we introduced <a href="https://weaviate.io/blog/8-bit-rotational-quantization" target="_blank" rel="noopener noreferrer" class="">Rotational Quantization</a> (or RQ) with 8-bit and 1-bit sizes. These quantization techniques allow for fast vector search, while reducing memory usage, and at better recall than comparable alternatives such as scalar and binary quantization.</p>
<p>Weaviate 1.39 extends RQ with 4-bit support, alongside a stack of quantization improvements in general. Rotations, distance kernels, encoding and the memory path have all been improved with net effect: 8-bit RQ is now <em>significantly faster</em> in 1.39 and 4-bit RQ provides similar recall with a <strong>45%</strong> heap reduction.</p>
<p>This post documents the story of that work, and along the way answers two questions people often ask: How does RQ hold up as datasets scale? And how does RQ compare to TurboQuant?</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="improvements">Improvements<a href="#improvements" class="hash-link" aria-label="Direct link to Improvements" title="Direct link to Improvements" translate="no">​</a></h2>
<p>Rotational quantization is based on <a href="https://arxiv.org/abs/2409.09913" target="_blank" rel="noopener noreferrer" class="">Extended-RaBitQ</a> with a structured fast rotation and simplified per-vector interval fitting to speed up encoding. Fast encoding performance (converting the original vector into its quantized representation) is an important part of a good quantization algorithm as it can have significant impacts on import performance.</p>
<p>The first step in these approaches is to multiply the original vector by a random rotation matrix. It may seem counter-intuitive but a random rotation matrix gives <a href="https://weaviate.io/blog/8-bit-rotational-quantization#the-universal-power-of-random-rotations-making-every-vector-well-suited-for-scalar-quantization" target="_blank" rel="noopener noreferrer" class="">better properties</a> to the vector in particular distributing the dimension values over the entire length of the quantization interval.</p>
<p>To speed up the random rotation we use Fast Walsh-Hadamard Transforms (FWHT) to rotate the original vector. In 1.39, we added SIMD support for FWHT which led to the below improvements while being bit-identical to the Go reference:</p>
<table><thead><tr><th>Transform</th><th>CPU</th><th style="text-align:right">1.38 (Go)</th><th style="text-align:right">1.39 (SIMD)</th><th style="text-align:right">Speedup</th></tr></thead><tbody><tr><td>FWHT64</td><td>Intel Xeon 8581C (amd64/AVX)</td><td style="text-align:right">81.3 ns</td><td style="text-align:right">26.5 ns</td><td style="text-align:right"><strong>3.1×</strong></td></tr><tr><td>FWHT256</td><td>Intel Xeon 8581C (amd64/AVX)</td><td style="text-align:right">515 ns</td><td style="text-align:right">84.5 ns</td><td style="text-align:right"><strong>6.1×</strong></td></tr><tr><td>FWHT64</td><td>Apple M1 (arm64/NEON)</td><td style="text-align:right">67.4 ns</td><td style="text-align:right">21.6 ns</td><td style="text-align:right"><strong>3.1×</strong></td></tr><tr><td>FWHT256</td><td>Apple M1 (arm64/NEON)</td><td style="text-align:right">428 ns</td><td style="text-align:right">96.2 ns</td><td style="text-align:right"><strong>4.5×</strong></td></tr></tbody></table>
<p>Together with some other enhancements to SIMD encode kernels, this led to the following net increases in encoding performance across the whole RQ family:</p>
<table><thead><tr><th>Quantizer</th><th>CPU</th><th style="text-align:right">1.38</th><th style="text-align:right">1.39</th><th style="text-align:right">Speedup</th></tr></thead><tbody><tr><td>RQ8</td><td>Intel Xeon 8581C (amd64/AVX)</td><td style="text-align:right">27.3 µs</td><td style="text-align:right">7.11 µs</td><td style="text-align:right"><strong>3.8×</strong></td></tr><tr><td>RQ1</td><td>Intel Xeon 8581C (amd64/AVX)</td><td style="text-align:right">15.2 µs</td><td style="text-align:right">6.84 µs</td><td style="text-align:right"><strong>2.2×</strong></td></tr><tr><td>RQ4 (uncentered)</td><td>Intel Xeon 8581C (amd64/AVX)</td><td style="text-align:right">—</td><td style="text-align:right">6.36 µs</td><td style="text-align:right"><strong>new in 1.39</strong></td></tr><tr><td>RQ4 (centered)</td><td>Intel Xeon 8581C (amd64/AVX)</td><td style="text-align:right">—</td><td style="text-align:right">8.08 µs</td><td style="text-align:right"><strong>new in 1.39</strong></td></tr><tr><td>RQ8</td><td>Apple M1 (arm64/NEON)</td><td style="text-align:right">14.7 µs</td><td style="text-align:right">6.18 µs</td><td style="text-align:right"><strong>2.4×</strong></td></tr><tr><td>RQ1</td><td>Apple M1 (arm64/NEON)</td><td style="text-align:right">13.0 µs</td><td style="text-align:right">6.18 µs</td><td style="text-align:right"><strong>2.1×</strong></td></tr><tr><td>RQ4 (uncentered)</td><td>Apple M1 (arm64/NEON)</td><td style="text-align:right">—</td><td style="text-align:right">5.65 µs</td><td style="text-align:right"><strong>new in 1.39</strong></td></tr><tr><td>RQ4 (centered)</td><td>Apple M1 (arm64/NEON)</td><td style="text-align:right">—</td><td style="text-align:right">7.00 µs</td><td style="text-align:right"><strong>new in 1.39</strong></td></tr></tbody></table>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="distance-kernels">Distance kernels<a href="#distance-kernels" class="hash-link" aria-label="Direct link to Distance kernels" title="Direct link to Distance kernels" translate="no">​</a></h3>
<p>The distance kernels were adapted to 4-bits via use of SIMD nibble (half byte) functions. We also switched to <code>UDOT</code> (arm64) and  <code>VPDPBUSD</code> (amd64) byte dot functions where possible, which also improved 8-bit quantization. Note the distance functions of 8-bit and 4-bit are similar but there is a big impact on memory bandwidth as explained in the following section.</p>
<p>Single query→code distance computation (cosine), 1.38 vs 1.39:</p>
<table><thead><tr><th>Kernel</th><th>CPU</th><th>d</th><th style="text-align:right">1.38</th><th style="text-align:right">1.39</th><th style="text-align:right">Speedup</th></tr></thead><tbody><tr><td>RQ8</td><td>Intel Xeon 8581C (amd64/AVX2)</td><td>768</td><td style="text-align:right">34.3 ns</td><td style="text-align:right">16.6 ns</td><td style="text-align:right">2.1×</td></tr><tr><td>RQ8</td><td>Intel Xeon 8581C (amd64/AVX2)</td><td>1024</td><td style="text-align:right">42.8 ns</td><td style="text-align:right">19.8 ns</td><td style="text-align:right">2.2×</td></tr><tr><td>RQ4 (uncentered)</td><td>Intel Xeon 8581C (amd64/AVX2)</td><td>768</td><td style="text-align:right">—</td><td style="text-align:right">16.0 ns</td><td style="text-align:right">new in 1.39</td></tr><tr><td>RQ4 (uncentered)</td><td>Intel Xeon 8581C (amd64/AVX2)</td><td>1024</td><td style="text-align:right">—</td><td style="text-align:right">17.7 ns</td><td style="text-align:right">new in 1.39</td></tr><tr><td>RQ4 (centered)</td><td>Intel Xeon 8581C (amd64/AVX2)</td><td>768</td><td style="text-align:right">—</td><td style="text-align:right">21.9 ns</td><td style="text-align:right">new in 1.39</td></tr><tr><td>RQ4 (centered)</td><td>Intel Xeon 8581C (amd64/AVX2)</td><td>1024</td><td style="text-align:right">—</td><td style="text-align:right">23.4 ns</td><td style="text-align:right">new in 1.39</td></tr><tr><td>RQ8</td><td>Apple M1 (arm64/NEON)</td><td>768</td><td style="text-align:right">24.9 ns</td><td style="text-align:right">17.0 ns</td><td style="text-align:right">1.5×</td></tr><tr><td>RQ8</td><td>Apple M1 (arm64/NEON)</td><td>1024</td><td style="text-align:right">31.1 ns</td><td style="text-align:right">20.0 ns</td><td style="text-align:right">1.6×</td></tr><tr><td>RQ4 (uncentered)</td><td>Apple M1 (arm64/NEON)</td><td>768</td><td style="text-align:right">—</td><td style="text-align:right">17.8 ns</td><td style="text-align:right">new in 1.39</td></tr><tr><td>RQ4 (uncentered)</td><td>Apple M1 (arm64/NEON)</td><td>1024</td><td style="text-align:right">—</td><td style="text-align:right">21.0 ns</td><td style="text-align:right">new in 1.39</td></tr><tr><td>RQ4 (centered)</td><td>Apple M1 (arm64/NEON)</td><td>768</td><td style="text-align:right">—</td><td style="text-align:right">24.5 ns</td><td style="text-align:right">new in 1.39</td></tr><tr><td>RQ4 (centered)</td><td>Apple M1 (arm64/NEON)</td><td>1024</td><td style="text-align:right">—</td><td style="text-align:right">27.0 ns</td><td style="text-align:right">new in 1.39</td></tr></tbody></table>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="prefetching-and-memory-access">Prefetching and memory access<a href="#prefetching-and-memory-access" class="hash-link" aria-label="Direct link to Prefetching and memory access" title="Direct link to Prefetching and memory access" translate="no">​</a></h3>
<p>To achieve sub 30ns distance kernels we also need the vectors to be cached effectively by the CPU cache. As graph ANN indices (like HNSW) have scattered DRAM access, memory bandwidth is often the <em>primary bottleneck</em> in performance - not the distance calculation itself.</p>
<p>To improve this in 1.39, we added efficient prefetching for both AMD64 and ARM64 architectures (and fixed a prefetching bug in AMD64 that was many years old). Prefetching helps by hinting to the processor what vectors will be used next. As HNSW expands to compute distances of neighbours we now prefetch or hint ahead of a batch of vector distance computations.</p>
<p>On a 1M-vector index (d=1536, ~800 MB of compressed codes, far beyond CPU cache), an A/B with only the prefetch hints removed shows they contribute <strong>7–11% query throughput</strong> (growing with ef) and <strong>12% faster</strong> imports.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="centering-and-outliers">Centering and outliers<a href="#centering-and-outliers" class="hash-link" aria-label="Direct link to Centering and outliers" title="Direct link to Centering and outliers" translate="no">​</a></h3>
<p>With the pipeline at hardware speed, we went looking for recall headroom at 4-bits. One open item was centering which we knew can add recall to many embedding datasets. Centering exploits the fact many embeddings have a non-zero mean vector. We compute this mean <code>μ</code> on a subset of the vectors and then encode <code>x − μ</code> against a single mean fitted at compression time, centering the query with the same mean, and add the cross-term back.</p>
<p>On many datasets centering showed significant recall improvements with recall@10 increasing by +0.1 to +6.1pp across several datasets, as embeddings tend to be <a href="https://arxiv.org/abs/2401.12143v2" target="_blank" rel="noopener noreferrer" class="">anisotropic</a>, particularly <a href="https://huggingface.co/blog/lightonai/lateon-regularization" target="_blank" rel="noopener noreferrer" class="">late-interaction models</a>. However some embedding models are regularized to remove this mean so we make the feature opt-in via a flag <code>centering=true</code>.</p>
<p>Additionally, when quantizing a vector the most extreme rotated coordinates add quantization noise to every dimension in that vector. By storing the largest two magnitude coordinates exactly, we managed to add +0.2 to +1.7pp recall on top of centering, and by careful packing of metadata bytes, we found we could store this in the standard 16 byte metadata header we already have.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="results">Results<a href="#results" class="hash-link" aria-label="Direct link to Results" title="Direct link to Results" translate="no">​</a></h2>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="recall">Recall<a href="#recall" class="hash-link" aria-label="Direct link to Recall" title="Direct link to Recall" translate="no">​</a></h3>
<p>The below table shows the recall@10 achievable by each quantization method. This table shows <em>brute force</em> recall excluding the ANN index to isolate the effect on quantization itself.</p>
<table><thead><tr><th>Dataset</th><th>RQ4 recall@10 / rescored@20</th><th>RQ4c recall@10 / rescored@20</th><th>RQ8 recall@10 / rescored@20</th></tr></thead><tbody><tr><td>dbpedia-ada002-1536-1M (cosine)</td><td>93.5 / 100.0</td><td><strong>96.8 / 100.0</strong></td><td>99.0 / 100.0</td></tr><tr><td>sphere-dpr-768-1M (dot)</td><td>90.9 / 99.4</td><td><strong>96.3 / 100.0</strong></td><td>98.2 / 100.0</td></tr><tr><td>sift-128-1M (l2)</td><td>81.4 / 97.2</td><td><strong>87.5 / 99.3</strong></td><td>96.7 / 99.9</td></tr><tr><td>glove-100-1.2M (cosine)</td><td>87.0 / 99.2</td><td><strong>89.9 / 99.8</strong></td><td>98.5 / 100.0</td></tr><tr><td>dbpedia-cohere-v2-4096-500k (dot)</td><td>98.1 / 100.0</td><td><strong>98.5 / 100.0</strong></td><td>99.9 / 100.0</td></tr><tr><td>msmarco-arctic-embed-m-768-1M (cosine)</td><td>94.7 / 100.0</td><td><strong>95.8 / 100.0</strong></td><td>99.3 / 100.0</td></tr><tr><td>nfcorpus-mlateon-mv-128 (maxsim)</td><td>72.0 / 88.6</td><td><strong>94.1 / 99.9</strong></td><td>93.4 / 99.9</td></tr><tr><td>scifact-mlateon-mv-128 (maxsim)</td><td>77.7 / 94.0</td><td><strong>94.5 / 100.0</strong></td><td>94.9 / 100.0</td></tr></tbody></table>
<p>Next and importantly, we show recall vs query performance in Weaviate using an HNSW index:</p>
<!-- -->
<img src="/assets/images/qps_recall-8ff87027c926062b388363bbc668dfef.png" alt="QPS vs recall@10 on dbpedia-openai-1M for RQ8, RQ4 and RQ4c in Weaviate 1.39, against RQ8 in 1.38" class="themedComponent_mlkZ themedComponent--light_NVdE"><img src="/assets/images/qps_recall_dark-1f38946eec48bc652fb2351a68c0cc70.png" alt="QPS vs recall@10 on dbpedia-openai-1M for RQ8, RQ4 and RQ4c in Weaviate 1.39, against RQ8 in 1.38" class="themedComponent_mlkZ themedComponent--dark_xIcU">
<p>It is quite visible the jump between 1.38 and 1.39 for the same 8-bit quantizer. Additionally the 4-bit performance to recall curves exceed 8-bit while using significantly less memory.</p>
<p>Here is the heap impact on the 1536 dimension vector dataset. Note you don't see half the memory usage (only 45%) because HNSW graph metadata (mainly the packed connections) also use memory. For reference storing this dataset unquantized would take 5.7GiB plus the graph metadata.</p>
<!-- -->
<img src="/assets/images/heap_usage-06469cdeb904ca971f58326394a94ff2.png" alt="Go heap in use on dbpedia-openai-1M: peak heap falls from 4.2 GiB with RQ8 in 1.38 to 2.3 GiB with RQ4 and RQ4c in 1.39" class="themedComponent_mlkZ themedComponent--light_NVdE"><img src="/assets/images/heap_usage_dark-5cd69f53968c6a3f2c92fc354c7a12fe.png" alt="Go heap in use on dbpedia-openai-1M: peak heap falls from 4.2 GiB with RQ8 in 1.38 to 2.3 GiB with RQ4 and RQ4c in 1.39" class="themedComponent_mlkZ themedComponent--dark_xIcU">
<p>Import times are also improved due to the faster encoding and distance functions. Imports on the same dataset drop 16% for RQ8 going from 1.38 to 1.39, and RQ4 and RQ4c come in 37% and 32% under the 1.38 baseline respectively.</p>
<!-- -->
<img src="/assets/images/import_time-e6830ff5f54f68f034b83fe0ae01bbe1.png" alt="Import time on dbpedia-openai-1M: RQ8 is 16% faster in 1.39 than 1.38, and RQ4 and RQ4c are 37% and 32% faster than the 1.38 baseline" class="themedComponent_mlkZ themedComponent--light_NVdE"><img src="/assets/images/import_time_dark-5d02554004921f4fd8e1b110e0e17440.png" alt="Import time on dbpedia-openai-1M: RQ8 is 16% faster in 1.39 than 1.38, and RQ4 and RQ4c are 37% and 32% faster than the 1.38 baseline" class="themedComponent_mlkZ themedComponent--dark_xIcU">
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="does-it-hold-at-scale">Does it hold at scale?<a href="#does-it-hold-at-scale" class="hash-link" aria-label="Direct link to Does it hold at scale?" title="Direct link to Does it hold at scale?" translate="no">​</a></h3>
<p>One interesting experiment we performed was to scale subsets of a shuffled sample of Meta's Sphere corpus (DPR, 768-dim, dot product) and then brute-force recall@10 against the exact ground truth, using 1,000 queries per point, from 1M to 250M vectors.</p>
<!-- -->
<img src="/assets/images/recall_vs_scale-d4dfa56cfac9f7cefbd116c296ba9014.png" alt="RQ quantizer recall is constant from 1M to 250M vectors" class="themedComponent_mlkZ themedComponent--light_NVdE"><img src="/assets/images/recall_vs_scale_dark-164d954820dab6eb911e2175871a9159.png" alt="RQ quantizer recall is constant from 1M to 250M vectors" class="themedComponent_mlkZ themedComponent--dark_xIcU">
<table><thead><tr><th>Quantizer</th><th>Recall 1M</th><th>Recall 10M</th><th>Recall 100M</th><th>Recall 250M</th></tr></thead><tbody><tr><td>rq8</td><td>97.15</td><td>97.09</td><td>97.09</td><td>96.90</td></tr><tr><td>rq4c</td><td>94.00</td><td>93.51</td><td>93.82</td><td>93.53</td></tr><tr><td>rq4</td><td>84.58</td><td>83.41</td><td>84.63</td><td>85.02</td></tr></tbody></table>
<p>The big result here is that recall is flat across a 1M-250M range. Even re-running with independent queries still produced a fairly tight band.</p>
<p>This graph also clearly shows the huge recall benefit that comes from rescoring (i.e. rescoring the top 20 vector distances with unquantized vectors), and how RQ4 centered can more accurately handle datasets with skewed mean.</p>
<p>A caveat of this result: although the quantizers can have close to scale free recall in this range, the ANN indices do have parameters that degrade with scale. One standard way to handle this is to shard the dataset appropriately (and sharding is usually recommended anyway when scaling to large datasets).</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="how-many-vectors-does-the-rq4-mean-need">How many vectors does the RQ4 mean need?<a href="#how-many-vectors-does-the-rq4-mean-need" class="hash-link" aria-label="Direct link to How many vectors does the RQ4 mean need?" title="Direct link to How many vectors does the RQ4 mean need?" translate="no">​</a></h3>
<p>RQ4 centered fits the mean μ, from a sample capped at 10,000 vectors by default. This is automatically completed with async indexing enabled. By fitting the mean on the first N vectors of a dataset and measuring its distance to the full-corpus mean we can measure the spread the interval covers:</p>
<!-- -->
<img src="/assets/images/mean_convergence-c3cbd5a5cf8d754a44bd21c866e1cb19.png" alt="Distance from the full-corpus mean as a function of the number of vectors used to fit it, on dbpedia-1M, for a random sample and for dataset order; both follow the sqrt(1/N - 1/M) sampling curve" class="themedComponent_mlkZ themedComponent--light_NVdE"><img src="/assets/images/mean_convergence_dark-d5aacd36b0f62270d2d0722397026878.png" alt="Distance from the full-corpus mean as a function of the number of vectors used to fit it, on dbpedia-1M, for a random sample and for dataset order; both follow the sqrt(1/N - 1/M) sampling curve" class="themedComponent_mlkZ themedComponent--dark_xIcU">
<p>At the 10k default the fitted mean sits within ~1% of a corpus radius of where 100x more data would put it. Fitting on the whole corpus instead is worth nothing measurable (largest difference across seven datasets: 0.20pp, with two datasets <em>ahead</em> on the 10k fit). Hence for RQ4 the default training limit is 10,000 which enables memory savings to start earlier.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="comparison-with-turboquant">Comparison with TurboQuant<a href="#comparison-with-turboquant" class="hash-link" aria-label="Direct link to Comparison with TurboQuant" title="Direct link to Comparison with TurboQuant" translate="no">​</a></h3>
<p>One question we get about RQ is how it compares to <a href="https://arxiv.org/abs/2504.19874" target="_blank" rel="noopener noreferrer" class="">TurboQuant</a>, another quantization technique using a random rotation but using Lloyd-Max codebooks instead of a uniform grid to quantize the vectors after rotation.</p>
<p>For the below comparison we ran a recall benchmark of our own implementation against a popular open-source TurboQuant <a href="https://github.com/0xsero/turboquant" target="_blank" rel="noopener noreferrer" class="">implementation</a>. If you would like more details comparing RaBitQ with TurboQuant we also recommend <a href="https://arxiv.org/abs/2604.19528" target="_blank" rel="noopener noreferrer" class="">Revisiting RaBitQ and TurboQuant: A Symmetric Comparison of Methods, Theory, and Experiments</a>, which goes further into details of comparing the two algorithms.</p>
<table><thead><tr><th>Dataset</th><th>RQ8</th><th>RQ4</th><th>RQ4c</th><th>4-bit TurboQuant (paper)</th><th>4-bit TurboQuant (renorm)</th><th>4-bit TurboQuant (centered+renorm)</th></tr></thead><tbody><tr><td>dbpedia-ada002-1536-1M (cosine)</td><td>99.0</td><td>93.5</td><td><strong>96.8</strong></td><td>87.4</td><td>94.5</td><td>96.4</td></tr><tr><td>sphere-dpr-768-1M (dot)</td><td>98.2</td><td>90.9</td><td><strong>96.3</strong></td><td>76.6</td><td>91.6</td><td>95.8</td></tr><tr><td>sift-128-1M (l2)</td><td>96.7</td><td>81.4</td><td><strong>87.5</strong></td><td>80.4</td><td>81.0</td><td>85.3</td></tr><tr><td>glove-100-1.2M (cosine)</td><td>98.5</td><td>87.0</td><td><strong>89.9</strong></td><td>79.0</td><td>85.4</td><td>86.9</td></tr><tr><td>dbpedia-cohere-v2-4096-500k (dot)</td><td>99.9</td><td>98.1</td><td><strong>98.5</strong></td><td>97.4</td><td>98.2</td><td>98.2</td></tr><tr><td>msmarco-arctic-embed-m-768-1M (cosine)</td><td>99.3</td><td>94.7</td><td>95.8</td><td>91.5</td><td>95.1</td><td><strong>95.9</strong></td></tr><tr><td>nfcorpus-mlateon-mv-128 (maxsim)</td><td>93.4</td><td>72.0</td><td><strong>94.1</strong></td><td>26.8</td><td>76.2</td><td>93.2</td></tr><tr><td>scifact-mlateon-mv-128 (maxsim)</td><td>94.9</td><td>77.7</td><td><strong>94.5</strong></td><td>36.7</td><td>81.1</td><td>94.1</td></tr></tbody></table>
<p>Here TurboQuant (paper) is the stock TurboQuant MSE variant in the paper, (renorm) adds renormalization which has been found to be important in improving the base TurboQuant, and (centered+renorm) also adds mean centering to make things comparable with centered RQ4.</p>
<p>Paper-faithful TurboQuant loses on every dataset (and notably collapses with highly anisotropic multi-vector models like mLateOn). When adding centering and renormalization, the gap is closer but RQ4c wins on 7/8 datasets.</p>
<p>Finally, you may have noticed there is no "8-bit" TurboQuant in most public implementations. This is because the SIMD codebook trick that works at 2 or 4 bits no longer works at 8 bits (with large performance decreases). RQ is more adaptable here and usable across the full range.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="using-4-bit-rq">Using 4-bit RQ<a href="#using-4-bit-rq" class="hash-link" aria-label="Direct link to Using 4-bit RQ" title="Direct link to Using 4-bit RQ" translate="no">​</a></h2>
<p>4-bit RQ ships in Weaviate 1.39 as a <code>bits</code> setting on the existing RQ quantizer.</p>
<div class="language-json codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-json codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token property">"vectorIndexConfig"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">  </span><span class="token property">"rq"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    </span><span class="token property">"enabled"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token boolean">true</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    "centering</span><span class="token operator">:</span><span class="token plain"> </span><span class="token boolean">true</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    </span><span class="token property">"bits"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token number">4</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">  </span><span class="token punctuation" style="color:rgb(248, 248, 242)">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token punctuation" style="color:rgb(248, 248, 242)">}</span><br></span></code></pre></div></div>
<p>In the Python client:</p>
<div class="language-python codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-python codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">from</span><span class="token plain"> weaviate</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">classes</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">config </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">import</span><span class="token plain"> Configure</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> Property</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> DataType</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">client</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">collections</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">create</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    name</span><span class="token operator">=</span><span class="token string" style="color:rgb(255, 121, 198)">"Recipes"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    vector_config</span><span class="token operator">=</span><span class="token plain">Configure</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">Vectors</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">text2vec_openai</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">        quantizer</span><span class="token operator">=</span><span class="token plain">Configure</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">VectorIndex</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">Quantizer</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">rq</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">            bits</span><span class="token operator">=</span><span class="token number">4</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">            centering</span><span class="token operator">=</span><span class="token boolean">True</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">        </span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    </span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    properties</span><span class="token operator">=</span><span class="token punctuation" style="color:rgb(248, 248, 242)">[</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">        Property</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain">name</span><span class="token operator">=</span><span class="token string" style="color:rgb(255, 121, 198)">"title"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> data_type</span><span class="token operator">=</span><span class="token plain">DataType</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">TEXT</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    </span><span class="token punctuation" style="color:rgb(248, 248, 242)">]</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><br></span></code></pre></div></div>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="conclusion">Conclusion<a href="#conclusion" class="hash-link" aria-label="Direct link to Conclusion" title="Direct link to Conclusion" translate="no">​</a></h2>
<p>We are excited to announce the suite of performance improvements we have done to Rotational Quantization, along with the new 4-bit size. Rotational quantization is tuned for fast encoding and distance calculations, achieving competitive recall and saving significant memory usage. Although we are keeping our default of 8-bit in Weaviate Cloud, we invite you to <a href="https://docs.weaviate.io/weaviate/configuration/compression/rq-compression#4-bit-rq" target="_blank" rel="noopener noreferrer" class="">try out 4-bit RQ</a> for cost savings and lower RAM usage.</p>
<hr>]]></content:encoded>
            <category>engineering</category>
            <category>quantization</category>
        </item>
        <item>
            <title><![CDATA[HFresh: Memory-Efficient Vector Search]]></title>
            <link>https://weaviate.io/blog/hfresh</link>
            <guid>https://weaviate.io/blog/hfresh</guid>
            <pubDate>Wed, 09 Sep 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[HFresh is Weaviate's disk-based vector index for memory-efficient vector search, combining low heap usage with incremental background maintenance.]]></description>
            <content:encoded><![CDATA[<p><img decoding="async" loading="lazy" alt="Scaling a vector database across multiple nodes." src="/assets/images/hero-0d5232f85002506f88763522238ef8ea.jpg" width="1730" height="909" class="img_ev3q"></p>
<br>
<p>HFresh is Weaviate's disk-based vector index for applications that prioritize lower memory use over peak query throughput. That tradeoff is useful for small applications with limited resources as well as large datasets. Weaviate Cloud's <a href="https://docs.weaviate.io/cloud/manage-clusters/create#optimization-profile" target="_blank" rel="noopener noreferrer" class="">Free Tier</a>, for example, uses HFresh by default through its Cost Optimized profile.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="understanding-hnsws-memory-bottleneck-in-similarity-search">Understanding HNSW's memory bottleneck in similarity search<a href="#understanding-hnsws-memory-bottleneck-in-similarity-search" class="hash-link" aria-label="Direct link to Understanding HNSW's memory bottleneck in similarity search" title="Direct link to Understanding HNSW's memory bottleneck in similarity search" translate="no">​</a></h2>
<p>When it comes to finding similar vectors quickly, HNSW (Hierarchical Navigable Small World) has become the gold standard. It's fast and accurate, but as datasets grow from millions to billions of vectors, HNSW reveals a fundamental constraint: its graph and vector cache are kept in memory.</p>
<p>HNSW is a graph-based index that organizes vectors into a hierarchical structure. At the top layer, you have a sparse graph with long-distance connections that help you quickly navigate to the right neighborhood. As you descend through the layers, the graphs become denser with more local connections, eventually guiding you to the most similar vectors at the bottom layer.</p>
<p><img decoding="async" loading="lazy" alt="HNSW organizes vectors into progressively denser graph layers that guide a query toward nearby vectors." src="/assets/images/hnsw-explained-09135d3f50d1e3724786918b5a29b8c0.png" width="1200" height="870" class="img_ev3q"></p>
<p>The question isn't whether HNSW is good. It absolutely is. If you need the lowest possible latency and highest throughput, HNSW is hard to beat. But many applications prioritize lower memory use and larger scale over peak query performance.</p>
<p>This is where disk-based indexes become interesting. What if you could trade some latency for much lower memory use and the ability to scale to larger datasets?</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="introducing-hfresh">Introducing HFresh<a href="#introducing-hfresh" class="hash-link" aria-label="Direct link to Introducing HFresh" title="Direct link to Introducing HFresh" translate="no">​</a></h2>
<p>HFresh is a modern disk-based vector index designed for high recall, strong update performance, and controlled query I/O at large scale. It builds on ideas introduced by the <a href="https://arxiv.org/pdf/2410.14452" target="_blank" rel="noopener noreferrer" class="">SPFresh</a> research paper, adapting the design to use battle-tested components already present in Weaviate.</p>
<p>At a high level, HFresh belongs to the family of partition-based vector indices. Instead of connecting every vector to neighbors in a global graph like HNSW, HFresh divides vectors into many small regions called postings. Each posting contains vectors that are close to each other in vector space and is stored on disk in an LSM store.</p>
<p><img decoding="async" loading="lazy" alt="HFresh architecture with an RQ8 centroid HNSW in memory pointing to RQ1 postings on disk." src="/assets/images/hfresh-structure-820476e5da431e832aae43961003be67.png" width="1200" height="976" class="img_ev3q"></p>
<p>To make this layout efficient, HFresh uses a two-stage search strategy.</p>
<p>First, a compact in-memory centroid index identifies which regions of the vector space are relevant to a query. Then, only corresponding postings are fetched from disk and searched in detail. By limiting disk reads to a small subset of the dataset, HFresh is designed to keep I/O bounded and latency predictable, even as the dataset grows into billions.</p>
<p>This structure is designed to support very large datasets while keeping performance predictable.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="freshness-without-rebuilds">Freshness without rebuilds<a href="#freshness-without-rebuilds" class="hash-link" aria-label="Direct link to Freshness without rebuilds" title="Direct link to Freshness without rebuilds" translate="no">​</a></h3>
<p>The key idea behind SPFresh, and inherited by HFresh, is that most updates only affect a small region of the vector space.</p>
<p>In traditional partition-based indexes, updates can accumulate and partitions can drift, eventually requiring a full rebuild to restore recall and latency, a process that can take hours or days at scale.</p>
<p>SPFresh shows that this is often unnecessary. In a well-structured partitioned index, inserting or deleting a vector typically only affects a small neighborhood of the vector space. Instead of rebuilding everything, you can maintain index quality through incremental rebalancing, using a small set of local operations.</p>
<ul>
<li class=""><strong>Splitting</strong> oversized postings</li>
<li class=""><strong>Merging</strong> undersized ones</li>
<li class=""><strong>Reassigning</strong> vectors when boundaries shift</li>
</ul>
<p>These operations run mostly asynchronously in the background, continuously repairing small local imbalances before they accumulate into global problems. The result is an index that stays fresh and well-balanced over time, without disruptive rebuild cycles.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="how-hfresh-builds-on-spfresh">How HFresh builds on SPFresh<a href="#how-hfresh-builds-on-spfresh" class="hash-link" aria-label="Direct link to How HFresh builds on SPFresh" title="Direct link to How HFresh builds on SPFresh" translate="no">​</a></h3>
<p>HFresh takes the core idea behind SPFresh and adapts it to fit Weaviate's architecture. The goal was not to reproduce the paper component by component, but to keep what makes the design so interesting:</p>
<ul>
<li class="">local maintenance instead of rebuilds</li>
<li class="">controlled query I/O</li>
<li class="">a clear separation between the in-memory routing layer and disk-based postings</li>
</ul>
<p>From there, we made a series of pragmatic choices. Instead of introducing entirely new ANN machinery, we reused battle-tested pieces already present in Weaviate and shaped them to serve this new layout. This means keeping the overall SPFresh philosophy, while rethinking some of its components to better match Weaviate's strengths around indexing, filtering, compression, and updates.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="hnsw-as-the-centroid-index">HNSW as the centroid index<a href="#hnsw-as-the-centroid-index" class="hash-link" aria-label="Direct link to HNSW as the centroid index" title="Direct link to HNSW as the centroid index" translate="no">​</a></h2>
<p>A key design choice in HFresh is the use of HNSW as the centroid index, rather than SPTAG.</p>
<p>SPTAG is the ANN index used in Microsoft's original SPANN design and carried over into SPFresh. It combines a partitioning tree with a graph, allowing queries to quickly navigate toward the closest centroids and, from there, the right posting lists. For Weaviate, however, HNSW was the more natural fit: it already plays that role very well.</p>
<p>HNSW is the most widely used vector index in Weaviate and one of the most battle-tested parts of the system. We understand its behavior well in production, across a wide range of workloads and dataset sizes. Reusing it for centroid search lets HFresh build on infrastructure that is already proven, rather than introducing a brand-new mechanism.</p>
<p>HNSW is also a strong fit for what the centroid index actually needs to do. In HFresh, the centroid layer is responsible for routing queries to the right postings quickly and accurately. That means it must remain compact, have low latency, and support frequent updates as postings evolve over time.</p>
<p>Centroids are not static: splits, merges, and reassignments continuously reshape the partitioning of the vector space, so the centroid index must be able to absorb many insertions and deletions without requiring expensive rebuilds.</p>
<p>Another advantage is that the centroid index can itself be quantized. Because the centroid layer is only used to identify promising regions of the vector space, HFresh can compress those vectors aggressively enough to reduce memory usage while maintaining the accuracy needed for strong recall. In fact, HFresh uses HNSW with RQ8, reducing memory usage of centroids by 4x.</p>
<p>Using HNSW here also means that improvements to HNSW automatically benefit HFresh. A good example is <a class="" href="/blog/speed-up-filtered-vector-search">ACORN</a>, which improves filtered search by making graph traversal more efficient when only part of the dataset matches a filter. Since HFresh relies on HNSW as the centroid layer, those improvements are not isolated: they strengthen HFresh's query path.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="quantization">Quantization<a href="#quantization" class="hash-link" aria-label="Direct link to Quantization" title="Direct link to Quantization" translate="no">​</a></h2>
<p>HFresh uses Rotational Quantization in two places, with two different compression levels.</p>
<p>The reason is that the two stages of search have different jobs. The centroid index routes the query to the right postings, so it needs enough precision to avoid sending the query to the wrong part of the vector space. The postings, on the other hand, are used to generate candidates. Their approximate scores are not the final ranking, because HFresh later rescores the best candidates using the original uncompressed vectors.</p>
<p>Rotational Quantization works by rotating vectors into a representation that is easier to compress, then reducing the precision of each dimension. HFresh uses:</p>
<ul>
<li class=""><strong>RQ8 for centroids</strong>, reducing centroid vector memory by <strong>4x</strong></li>
<li class=""><strong>RQ1 for postings</strong>, reducing stored vector data by up to <strong>32x</strong> compared to 32-bit floats</li>
</ul>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="rq8-for-the-centroid-index">RQ8 for the centroid index<a href="#rq8-for-the-centroid-index" class="hash-link" aria-label="Direct link to RQ8 for the centroid index" title="Direct link to RQ8 for the centroid index" translate="no">​</a></h3>
<p>The first stage of HFresh search uses an HNSW index over centroids. This in-memory index identifies which postings are likely to contain the nearest neighbors for a query.</p>
<p>HFresh uses RQ8 here because routing mistakes are expensive. If the centroid search misses the right region, the later posting scan may never see the true nearest neighbors. RQ8 gives a strong compromise: it makes centroid-vector payloads approximately <strong>4x smaller</strong> before overhead while keeping enough precision for accurate routing.</p>
<p>This works especially well because the centroid index is much smaller than the full vector dataset. HFresh can afford a higher-precision compression format for centroids, while still keeping the in-memory layer compact.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="rq1-for-postings">RQ1 for postings<a href="#rq1-for-postings" class="hash-link" aria-label="Direct link to RQ1 for postings" title="Direct link to RQ1 for postings" translate="no">​</a></h3>
<p>After HFresh has selected the most promising postings, it scans the vectors stored inside them. This stage has a different tradeoff.</p>
<p>Postings live on disk, so their size directly affects storage cost and query I/O. HFresh stores posting vectors with RQ1, where each dimension is represented with a single bit. Compared to 32-bit float vectors, that is up to a <strong>32x reduction</strong> in vector storage.</p>
<p>That aggressive compression makes each posting smaller and cheaper to read. It also makes the first-pass distance computation fast enough to scan many candidates.</p>
<p>HFresh does not rely on RQ1 scores for the final ranking. Instead, RQ1 is used to build a candidate set. HFresh then fetches the original uncompressed vectors for the top candidates and recomputes exact distances during rescoring. This keeps disk reads small without giving up final ranking quality.</p>
<p><img decoding="async" loading="lazy" alt="HFresh query path from the in-memory centroid HNSW through selected RQ1 postings and full-precision rescoring." src="/assets/images/hfresh-query-path-3bac75e7e11cb92ac3ea8cb7de1a67cb.png" width="1200" height="1185" class="img_ev3q"></p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="background-operations">Background operations<a href="#background-operations" class="hash-link" aria-label="Direct link to Background operations" title="Direct link to Background operations" translate="no">​</a></h2>
<p>The reason HFresh can stay balanced over time without rebuilds is that maintenance is built directly into the index. Instead of letting imbalances accumulate and then fixing everything in one large offline job, HFresh breaks down maintenance into small background tasks that can be processed continuously.</p>
<p>In practice, most foreground writes stay simple: vectors are appended quickly, and follow-up work is pushed to background queues. Those tasks are persisted in dedicated on-disk queues, so they survive restarts and can be drained incrementally by the scheduler.</p>
<p>HFresh organizes this work into three main background task types: split, merge, and reassign.</p>
<p><img decoding="async" loading="lazy" alt="An oversized posting split into two balanced postings with new centroids." src="/assets/images/hfresh-split-0212479c5b6ff6fbb1d637aa3eb8c079.png" width="1200" height="520" class="img_ev3q"></p>
<p><strong>Split:</strong> When a posting grows too large, HFresh splits it. The posting is loaded, stale entries are garbage-collected, its vectors are divided into two balanced groups using the Balanced K-Means algorithm, and two new centroids are created to replace the old one. This keeps postings from growing too much, which would make disk reads heavier and routing less precise.</p>
<p><img decoding="async" loading="lazy" alt="An undersized posting merged into a nearby posting under one centroid." src="/assets/images/hfresh-merge-5ab946dabe55fd855f23513a8fa235fd.png" width="1200" height="520" class="img_ev3q"></p>
<p><strong>Merge:</strong> The opposite problem is postings that become too small. That can happen after deletes or simply as the data distribution evolves. In those cases, HFresh looks for a nearby posting that can absorb the smaller one without becoming too large itself. If it finds a good candidate, it merges the two and removes the extra centroid. This prevents the index from fragmenting into too many tiny postings.</p>
<p><img decoding="async" loading="lazy" alt="A vector reassigned from one posting to a better neighboring posting." src="/assets/images/hfresh-reassign-a4be01751bb29f958fbb1d5e2b0f8311.png" width="1200" height="520" class="img_ev3q"></p>
<p><strong>Reassign:</strong> After a split or a merge, some vectors may no longer belong in the posting where they are currently stored. That's where reassignment comes in. The SPFresh paper describes a protocol called LIRE (<strong>L</strong>ightweight <strong>I</strong>ncremental <strong>Re</strong>balancing) which, after a split, checks whether some vectors would now fit better under one of the new centroids, or even under a neighboring posting. After a merge, it checks whether some vectors that were absorbed should really be moved elsewhere instead. These reassignments let HFresh progressively correct mistakes instead of trying to get everything perfect in one step.</p>
<p>Together, these background operations form a continuous balancing loop. Inserts make local changes, and the index quietly tidies itself up afterward. The result is an index that stays fresh over time without disruptive rebuild cycles.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="filtered-search">Filtered search<a href="#filtered-search" class="hash-link" aria-label="Direct link to Filtered search" title="Direct link to Filtered search" translate="no">​</a></h2>
<p>Filtered vector search adds another constraint: results must be similar to the query vector while also satisfying the filter. In an e-commerce search, for example, that might mean finding similar products from specific brands, within a price range, and currently in stock.</p>
<p>HFresh uses an allow list, represented as a bitmap, to track the document IDs that satisfy the filter. It then chooses between two search strategies based on the number of matching vectors.</p>
<p>For highly selective filters, running the full HFresh pipeline can cost more than searching the matching subset directly. When the allow list contains fewer than 5,000 IDs, HFresh bypasses centroid routing and posting scans, fetches the original vectors for those IDs, and computes exact distances over them. The current 5,000-ID cutoff is a fixed internal heuristic, not a configurable threshold or a general tuning recommendation.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="posting-aware-filtering">Posting-aware filtering<a href="#posting-aware-filtering" class="hash-link" aria-label="Direct link to Posting-aware filtering" title="Direct link to Posting-aware filtering" translate="no">​</a></h3>
<p>For broader filters, HFresh uses its regular two-stage search with a posting-aware form of prefiltering. The filter identifies matching objects, but the centroid HNSW routes queries to postings rather than individual objects. HFresh bridges those two levels using metadata that records which vector IDs belong to each posting.</p>
<p>The process is:</p>
<ol>
<li class="">Translate the object-level allow list into posting eligibility using the posting metadata.</li>
<li class="">Navigate the centroid HNSW with <a class="" href="/blog/speed-up-filtered-vector-search">ACORN</a>, selecting postings that can contribute at least one matching vector.</li>
<li class="">Read the selected postings and reapply the original allow list while scanning their compressed vectors.</li>
<li class="">Rescore the top candidates using their original uncompressed vectors.</li>
</ol>
<p>Because HFresh can replicate a vector across multiple postings, it also tracks which matching vectors have already contributed to posting selection. This avoids reading multiple postings solely because they contain replicas of the same match. Together, posting-level selection and vector-level checks reduce unnecessary disk reads while ensuring that the final results satisfy the filter.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="how-to-use-hfresh">How to use HFresh<a href="#how-to-use-hfresh" class="hash-link" aria-label="Direct link to How to use HFresh" title="Direct link to How to use HFresh" translate="no">​</a></h2>
<p>To use HFresh, configure it as the vector index when creating a collection.</p>
<p>Here is an example using the Python client:</p>
<div class="language-python codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-python codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">from</span><span class="token plain"> weaviate</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">classes</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">config </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">import</span><span class="token plain"> Configure</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> VectorDistances</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">collection </span><span class="token operator">=</span><span class="token plain"> client</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">collections</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">create</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    name</span><span class="token operator">=</span><span class="token string" style="color:rgb(255, 121, 198)">"Article"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    vector_config</span><span class="token operator">=</span><span class="token plain">Configure</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">Vectors</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">self_provided</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">        name</span><span class="token operator">=</span><span class="token string" style="color:rgb(255, 121, 198)">"Title"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">        vector_index_config</span><span class="token operator">=</span><span class="token plain">Configure</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">VectorIndex</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">hfresh</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">            distance_metric</span><span class="token operator">=</span><span class="token plain">VectorDistances</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">COSINE</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">        </span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    </span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><br></span></code></pre></div></div>
<div class="theme-admonition theme-admonition-tip admonition_xJq3 alert alert--success"><div class="admonitionHeading_Gvgb"><span class="admonitionIcon_Rf37"><svg viewBox="0 0 12 16"><path fill-rule="evenodd" d="M6.5 0C3.48 0 1 2.19 1 5c0 .92.55 2.25 1 3 1.34 2.25 1.78 2.78 2 4v1h5v-1c.22-1.22.66-1.75 2-4 .45-.75 1-2.08 1-3 0-2.81-2.48-5-5.5-5zm3.64 7.48c-.25.44-.47.8-.67 1.11-.86 1.41-1.25 2.06-1.45 3.23-.02.05-.02.11-.02.17H5c0-.06 0-.13-.02-.17-.2-1.17-.59-1.83-1.45-3.23-.2-.31-.42-.67-.67-1.11C2.44 6.78 2 5.65 2 5c0-2.2 2.02-4 4.5-4 1.22 0 2.36.42 3.22 1.19C10.55 2.94 11 3.94 11 5c0 .66-.44 1.78-.86 2.48zM4 14h5c-.23 1.14-1.3 2-2.5 2s-2.27-.86-2.5-2z"></path></svg></span>Tuning HFresh</div><div class="admonitionContent_BuS1"><p>Start with the defaults. If recall is too low, increase:</p><ul>
<li class=""><code>search_probe</code> to search more postings per query.</li>
<li class=""><code>quantizer.rescore_limit</code> to rescore more candidates using full-precision vectors.</li>
</ul><p>Both settings can be changed without rebuilding the index.</p></div></div>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="experiments">Experiments<a href="#experiments" class="hash-link" aria-label="Direct link to Experiments" title="Direct link to Experiments" translate="no">​</a></h2>
<p>We benchmarked uncompressed HNSW, HNSW with RQ1, HNSW with RQ8, and HFresh on the DBpedia OpenAI 1M dataset. HNSW indexes were built with <code>efConstruction=256</code> and <code>maxConnections=16</code>.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="heap-usage">Heap usage<a href="#heap-usage" class="hash-link" aria-label="Direct link to Heap usage" title="Direct link to Heap usage" translate="no">​</a></h3>
<p><img decoding="async" loading="lazy" alt="Heap memory usage at rest for HFresh, uncompressed HNSW, HNSW with RQ1, and HNSW with RQ8." src="/assets/images/vector-memory-chart-841fc0db359c706ae89f458429ec915b.png" width="2400" height="1600" class="img_ev3q"></p>
<p>These measurements report Go heap usage, not total process or system memory. HFresh also relies on OS-managed caching for its on-disk data, which is not captured by the heap figures.</p>
<p>The clearest difference is heap usage at rest. HFresh uses 239 MB of heap, compared with 6.67 GB for uncompressed HNSW.</p>
<p>HFresh also uses less heap than quantized HNSW. HNSW with RQ1 uses 715 MB, approximately 3x as much as HFresh, while HNSW with RQ8 uses 2.38 GB, approximately 10x as much.</p>
<p>This difference follows directly from HFresh's architecture. HFresh keeps the RQ8-compressed centroid index and supporting metadata in memory while storing compressed postings on disk. Posting membership, vector versions and deletion state, and posting sizes also consume heap and grow with the dataset, but this layout reduces the heap required for index data.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="query-throughput">Query throughput<a href="#query-throughput" class="hash-link" aria-label="Direct link to Query throughput" title="Direct link to Query throughput" translate="no">​</a></h3>
<p><img decoding="async" loading="lazy" alt="Query throughput versus recall for HFresh, uncompressed HNSW, HNSW with RQ1, and HNSW with RQ8." src="/assets/images/qps-recall-4316f2c564751c8920e03bb6481f225a.png" width="2400" height="1600" class="img_ev3q"></p>
<p>The QPS-recall curve shows the query-performance side of HFresh's heap advantage.</p>
<p>At comparable recall, HNSW and its quantized variants deliver substantially higher throughput than HFresh. This is expected: HNSW searches an in-memory graph, while HFresh reads selected postings from disk and fetches original vectors for rescoring.</p>
<p>These results clarify when to choose each index. HNSW remains the better option when the lowest latency and highest throughput matter most. HFresh is designed for workloads where keeping the full index in memory is too expensive and lower throughput is an acceptable tradeoff for a much smaller heap footprint.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="scaling-to-one-billion-vectors">Scaling to one billion vectors<a href="#scaling-to-one-billion-vectors" class="hash-link" aria-label="Direct link to Scaling to one billion vectors" title="Direct link to Scaling to one billion vectors" translate="no">​</a></h3>
<p>Separately from the DBpedia benchmarks, we tested HFresh index construction with one billion randomly generated 256-dimensional vectors. We used default index-construction settings and imported batches of 1,000 with 12 workers.</p>
<table><thead><tr><th>Metric</th><th>Result</th></tr></thead><tbody><tr><td>Dataset</td><td><strong>1 billion 256-dimensional vectors</strong></td></tr><tr><td>Compute</td><td><strong>32 vCPUs, 256 GB RAM</strong> (<code>n2-highmem-32</code>)</td></tr><tr><td>Storage</td><td><strong>4 TB SSD Persistent Disk</strong> (<code>pd-ssd</code>)</td></tr><tr><td>Peak VM memory usage</td><td><strong>204 GB</strong></td></tr><tr><td>VM memory usage after restart</td><td><strong>54 GB</strong></td></tr><tr><td>Go heap after restart</td><td><strong>47 GB</strong></td></tr><tr><td>Peak disk usage</td><td><strong>3.09 TB</strong></td></tr><tr><td>Disk usage after import</td><td><strong>2.28 TB</strong></td></tr></tbody></table>
<p>The run successfully constructed the billion-vector HFresh index. No recall or QPS measurements were collected for this scale test.</p>
<p>The VM memory measurements come from GCP system metrics, while the heap measurement comes from a Go heap profile.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="conclusion">Conclusion<a href="#conclusion" class="hash-link" aria-label="Direct link to Conclusion" title="Direct link to Conclusion" translate="no">​</a></h2>
<p>HFresh gives Weaviate a disk-based index for memory-efficient vector search, from small applications to large, mutable datasets. By keeping a compact centroid index and supporting metadata in memory and maintaining disk-resident postings incrementally, it reduces the heap required for index data without relying on full index rebuilds. HNSW remains the better choice when the lowest latency and highest throughput matter most; HFresh is designed for workloads where a smaller heap footprint justifies lower query throughput.</p>
<p>HFresh was introduced as a technical preview in Weaviate 1.36 and became generally available in Weaviate 1.38. See the <a href="https://docs.weaviate.io/weaviate/concepts/vector-index#hfresh-index" target="_blank" rel="noopener noreferrer" class="">documentation</a> to get started.</p>
<p>If you are evaluating HFresh for a large-scale workload, we would like to hear about your dataset, performance requirements, and results.</p>
<!-- -->
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="ready-to-start-building">Ready to start building?<a href="#ready-to-start-building" class="hash-link" aria-label="Direct link to Ready to start building?" title="Direct link to Ready to start building?" translate="no">​</a></h2>
<p>Check out the <a href="https://docs.weaviate.io/weaviate/quickstart" target="_blank" rel="noopener noreferrer" class="">Quickstart tutorial</a>, or <a href="https://console.weaviate.cloud/?utm_source=blog&amp;utm_medium=website&amp;utm_campaign=blog_signup&amp;utm_content=hfresh&amp;utm_term=ready-to-start-building" target="_blank" rel="noopener noreferrer">sign up for a free Weaviate Cloud account</a>.</p>
<!-- -->
]]></content:encoded>
            <category>engineering</category>
            <category>concepts</category>
            <category>search</category>
        </item>
        <item>
            <title><![CDATA[Building Foundry Part 3: From archive to creative search]]></title>
            <link>https://weaviate.io/blog/building-foundry-creative-search</link>
            <guid>https://weaviate.io/blog/building-foundry-creative-search</guid>
            <pubDate>Tue, 08 Sep 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[Part 3: We turn a messy creative archive into a searchable library using a manifest, Weaviate, and hybrid search.]]></description>
            <content:encoded><![CDATA[<figure><video width="100%" autoplay="" loop="" muted="" controls=""><source src="/assets/medias/Foundry_test-938bdd9863b5e9d757de0d7c1e5ca277.mp4" type="video/mp4"><p>Your browser does not support the video tag.</p></video><figcaption>Foundry searching the creative archive</figcaption></figure>
<blockquote>
<p><strong>Building Foundry</strong><br>
<!-- -->A practical series on creative workflows, semantic search, and Weaviate.</p>
</blockquote>
<p>Read the previous post in the series: <a class="" href="/blog/building-foundry-where-workflows-break">Part 2: Where creative workflows break</a>.</p>
<p>Part 1 introduced the problem. Part 2 showed why familiar ways of organising work become less reliable as an archive grows. Now we are going to build the solution.</p>
<p>Foundry turns an existing archive into a searchable creative library. It scans the files, records what it finds, prepares each asset for retrieval, and synchronises the result with Weaviate. Nothing is moved or renamed. Every result still leads back to its original source.</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token plain">creative archive</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">      ↓</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">read-only scanner</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">      ↓</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">manifest and descriptions</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">      ↓</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">Weaviate collection</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">      ↓</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">keyword, semantic, or hybrid search</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">      ↓</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">source asset</span><br></span></code></pre></div></div>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="starting-with-the-archive-we-already-have">Starting with the archive we already have<a href="#starting-with-the-archive-we-already-have" class="hash-link" aria-label="Direct link to Starting with the archive we already have" title="Direct link to Starting with the archive we already have" translate="no">​</a></h2>
<p>Our test archive contains 23 assets from five fictional projects. Inside are concept art, design exports, production notes, audio, video, and reference images.</p>
<p>The names are deliberately inconsistent:</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token plain">final_FINAL_v7.svg</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">BROLL_NEW2.svg</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">scene_14_USE_THIS.svg</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">logo_options_FINAL3.svg</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">bridge_texture.svg</span><br></span></code></pre></div></div>
<p>That mess is intentional. Foundry should be useful with the archive a team has today, not the perfectly organised archive it may never have time to create.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="step-1-scan-without-changing-the-source">Step 1: scan without changing the source<a href="#step-1-scan-without-changing-the-source" class="hash-link" aria-label="Direct link to Step 1: scan without changing the source" title="Direct link to Step 1: scan without changing the source" translate="no">​</a></h2>
<p>Foundry begins with a read-only scan. It walks the selected folder and records facts about every supported file.</p>
<div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token plain">npm install</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">npm run demo</span><br></span></code></pre></div></div>
<p>The scanner captures the source path, project, file type, size, modified date, and a content hash. It writes the result to <code>output/manifest.json</code>.</p>
<p><img decoding="async" loading="lazy" alt="Foundry archive inventory showing references, concepts, and video assets" src="/assets/images/image-02-c7d2dcfecdf8336846378b8b672a5654.jpg" width="950" height="506" class="img_ev3q"></p>
<p>The content hash gives each asset a stable identity. It lets Foundry detect changes even when a filename stays the same and skip work when nothing has changed.</p>
<p>The browser turns that inventory into something visual. Images have previews, videos can be played, and documents remain visible without thumbnails.</p>
<p>This first checkpoint matters because search cannot find what the scanner missed.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="step-2-prepare-records-for-retrieval">Step 2: prepare records for retrieval<a href="#step-2-prepare-records-for-retrieval" class="hash-link" aria-label="Direct link to Step 2: prepare records for retrieval" title="Direct link to Step 2: prepare records for retrieval" translate="no">​</a></h2>
<p>The manifest tells us what exists. The next step is to describe what those files contain.</p>
<p>The preparation stage adds descriptions, tags, extracted text, relationship roles, and a source URI. A prepared image record looks like this:</p>
<div class="language-json codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-json codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token punctuation" style="color:rgb(248, 248, 242)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">  </span><span class="token property">"fileName"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:rgb(255, 121, 198)">"rain-floor.jpg"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">  </span><span class="token property">"relativePath"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:rgb(255, 121, 198)">"RAIN TRAILER/References/rain-floor.jpg"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">  </span><span class="token property">"project"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:rgb(255, 121, 198)">"RAIN TRAILER"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">  </span><span class="token property">"assetType"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:rgb(255, 121, 198)">"image"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">  </span><span class="token property">"relationshipRole"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:rgb(255, 121, 198)">"reference"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">  </span><span class="token property">"description"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:rgb(255, 121, 198)">"Heavy rain striking a reflective floor with bright droplets and bokeh."</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">  </span><span class="token property">"tags"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">[</span><span class="token string" style="color:rgb(255, 121, 198)">"rain"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> </span><span class="token string" style="color:rgb(255, 121, 198)">"wet floor"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> </span><span class="token string" style="color:rgb(255, 121, 198)">"reflection"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> </span><span class="token string" style="color:rgb(255, 121, 198)">"atmosphere"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">]</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">  </span><span class="token property">"sourceUri"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:rgb(255, 121, 198)">"foundry://RAIN TRAILER/References/rain-floor.jpg"</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token punctuation" style="color:rgb(248, 248, 242)">}</span><br></span></code></pre></div></div>
<p>The <code>foundry://</code> URI points back to the asset without treating Weaviate as file storage. A production version could use a DAM link, mounted path, S3 URL, or application route.</p>
<p>For now, the demo uses a small enrichment manifest so every run produces the same result. Later versions can generate this context from image captions, OCR, transcripts, and video keyframes.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="step-3-synchronise-with-weaviate">Step 3: synchronise with Weaviate<a href="#step-3-synchronise-with-weaviate" class="hash-link" aria-label="Direct link to Step 3: synchronise with Weaviate" title="Direct link to Step 3: synchronise with Weaviate" translate="no">​</a></h2>
<p>Before synchronisation, Foundry shows exactly what will be indexed. The user can review descriptions, metadata, and source paths before anything reaches Weaviate.</p>
<p><img decoding="async" loading="lazy" alt="Foundry ingestion review showing objects and vectorised fields" src="/assets/images/image-03-4980e2194f317e4e2605a05af706aa52.jpg" width="1000" height="300" class="img_ev3q"></p>
<p>The application then creates or updates the <code>Foundry</code> collection. Weaviate generates embeddings and stores them beside the metadata. Each object keeps its source path and rights status.</p>
<p><img decoding="async" loading="lazy" alt="Foundry showing a completed Weaviate synchronisation" src="/assets/images/image-04-ed437f01a06cbbfc6eafe4dfda59efb3.jpg" width="1100" height="300" class="img_ev3q"></p>
<p>Running the process again does not create duplicates. Deterministic identifiers ensure that each asset updates the same object.</p>
<p>The same workflow is available from the command line:</p>
<div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token plain">npm run scan</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">npm run ingest:prepare</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">npm run ingest:cloud</span><br></span></code></pre></div></div>
<p>Cloud credentials stay in a local <code>.env</code> file:</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token plain">WEAVIATE_URL=https://your-cluster.weaviate.network</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">WEAVIATE_API_KEY=replace-with-a-read-write-api-key</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">WEAVIATE_COLLECTION=Foundry</span><br></span></code></pre></div></div>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="step-4-search-the-archive">Step 4: search the archive<a href="#step-4-search-the-archive" class="hash-link" aria-label="Direct link to Step 4: search the archive" title="Direct link to Step 4: search the archive" translate="no">​</a></h2>
<p>Once synchronisation finishes, the archive becomes a live search workspace.</p>
<p>The first test query is easy to describe but hard to map to a filename:</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token plain">white rabbit in a grassy landscape</span><br></span></code></pre></div></div>
<p><img decoding="async" loading="lazy" alt="Foundry hybrid retrieval returning rabbit and landscape assets" src="/assets/images/image-05-8c9d8538cc7bd224658de53871d02fd9.jpg" width="950" height="506" class="img_ev3q"></p>
<p>The results include a rabbit reference, the Big Buck Bunny trailer, and related landscape imagery. There is no need to remember a filename or folder. The user describes what they remember and Foundry brings the relevant work back into view.</p>
<p>Foundry exposes three retrieval modes:</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token plain">keyword  → exact words and names</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">semantic → meaning represented by embeddings</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">hybrid   → keyword and semantic signals combined</span><br></span></code></pre></div></div>
<p>Keyword search works when someone remembers a filename or production term. Semantic search works when they remember the content. Hybrid search brings both kinds of memory into one result set.</p>
<p>Filters make those results practical. Users can narrow the archive by project, file type, or relationship role. The same pattern can support approval status, rights, expiry dates, and delivery formats.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="what-the-build-proves">What the build proves<a href="#what-the-build-proves" class="hash-link" aria-label="Direct link to What the build proves" title="Direct link to What the build proves" translate="no">​</a></h2>
<p>The prototype now completes the journey from source folder to useful result:</p>
<ul>
<li class="">It scans a nested archive without changing the source files.</li>
<li class="">It creates stable records and detects changes with content hashes.</li>
<li class="">It enriches records before ingestion instead of relying on filenames alone.</li>
<li class="">It stores searchable records and managed embeddings in Weaviate.</li>
<li class="">It compares keyword, semantic, and hybrid retrieval on the same archive.</li>
<li class="">It returns images and video with links back to their source.</li>
</ul>
<p>Foundry is still a prototype. Automatic enrichment, incremental rescans, rights-aware filtering, and relevance feedback would be the next update to the project.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="run-foundry">Run Foundry<a href="#run-foundry" class="hash-link" aria-label="Direct link to Run Foundry" title="Direct link to Run Foundry" translate="no">​</a></h2>
<p>The project is available on <a href="https://github.com/Shan-Weaviate/foundry" target="_blank" rel="noopener noreferrer" class="">GitHub</a>.</p>
<div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token plain">cp .env.example .env</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"># Add your Weaviate Cloud URL and API key</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">npm install</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">npm run demo</span><br></span></code></pre></div></div>
<p>Use Node.js 22 or newer for cloud synchronisation and live search. The local inventory can run without cloud credentials.</p>
<div class="theme-admonition theme-admonition-tip admonition_xJq3 alert alert--success"><div class="admonitionHeading_Gvgb"><span class="admonitionIcon_Rf37"><svg viewBox="0 0 12 16"><path fill-rule="evenodd" d="M6.5 0C3.48 0 1 2.19 1 5c0 .92.55 2.25 1 3 1.34 2.25 1.78 2.78 2 4v1h5v-1c.22-1.22.66-1.75 2-4 .45-.75 1-2.08 1-3 0-2.81-2.48-5-5.5-5zm3.64 7.48c-.25.44-.47.8-.67 1.11-.86 1.41-1.25 2.06-1.45 3.23-.02.05-.02.11-.02.17H5c0-.06 0-.13-.02-.17-.2-1.17-.59-1.83-1.45-3.23-.2-.31-.42-.67-.67-1.11C2.44 6.78 2 5.65 2 5c0-2.2 2.02-4 4.5-4 1.22 0 2.36.42 3.22 1.19C10.55 2.94 11 3.94 11 5c0 .66-.44 1.78-.86 2.48zM4 14h5c-.23 1.14-1.3 2-2.5 2s-2.27-.86-2.5-2z"></path></svg></span>tip</div><div class="admonitionContent_BuS1"><p>Explore the <a href="https://github.com/Shan-Weaviate/foundry" target="_blank" rel="noopener noreferrer" class="">Foundry repository</a> and follow the README to scan the sample archive or connect your own Weaviate Cloud collection.</p></div></div>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="from-hidden-files-to-useful-history">From hidden files to useful history<a href="#from-hidden-files-to-useful-history" class="hash-link" aria-label="Direct link to From hidden files to useful history" title="Direct link to From hidden files to useful history" translate="no">​</a></h2>
<p>Foundry began with a familiar creative frustration: remembering the work but not where it lives.</p>
<p>It does not replace the folders, tools, or habits behind that work. It gives the archive a new way to reveal itself. An asset that once depended on the right filename, folder, or colleague can now be found through the idea behind it.</p>
<p>The archive stops being a place where finished work disappears. It becomes creative material again.</p>
<!-- -->
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="ready-to-start-building">Ready to start building?<a href="#ready-to-start-building" class="hash-link" aria-label="Direct link to Ready to start building?" title="Direct link to Ready to start building?" translate="no">​</a></h2>
<p>Check out the <a href="https://docs.weaviate.io/weaviate/quickstart" target="_blank" rel="noopener noreferrer" class="">Quickstart tutorial</a>, or <a href="https://console.weaviate.cloud/?utm_source=blog&amp;utm_medium=website&amp;utm_campaign=blog_signup&amp;utm_content=building-foundry-creative-search&amp;utm_term=ready-to-start-building" target="_blank" rel="noopener noreferrer">sign up for a free Weaviate Cloud account</a>.</p>
<!-- -->
]]></content:encoded>
            <category>creative-ai</category>
            <category>workflows</category>
            <category>search</category>
            <category>weaviate</category>
        </item>
        <item>
            <title><![CDATA[How to extract meaning from charts and tables in PDFs]]></title>
            <link>https://weaviate.io/blog/charts-tables-pdfs</link>
            <guid>https://weaviate.io/blog/charts-tables-pdfs</guid>
            <pubDate>Tue, 01 Sep 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[PDFs full of charts and tables are notoriously hard to put through a traditional RAG pipeline. In this post, we show how late-interaction multi-vector retrieval lets you search PDFs by what the page looks like: no OCR, no chunking, no text extraction.]]></description>
            <content:encoded><![CDATA[<p><img decoding="async" loading="lazy" alt="Gross margin trend chart from NVIDIA&amp;#39;s Q2 FY26 deck, retrieved by a single text query without any OCR." src="/assets/images/nvidia-gross-margin-trend-e0d7228ff81c186427895df91b474186.png" width="2000" height="1125" class="img_ev3q"></p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="intro">Intro<a href="#intro" class="hash-link" aria-label="Direct link to Intro" title="Direct link to Intro" translate="no">​</a></h2>
<p>If you have ever tried to put a stack of investor decks, scientific papers, or annual reports through a RAG pipeline, then you know the drill: set up an Optical Character Recognition (OCR) or text-extraction step, pick a chunking strategy, embed text, and finally retrieve information. After going through all this, someone may ask a question about revenue in <code>Q2 FY25</code>, and your retrieval would return three pages of unrelated bullet points because the actual answer is in a bar chart that was invisible to your index.</p>
<p>This used to be what people had to do — just leave out the interesting parts of a PDF from RAG such as bar charts with trends, comparison tables, architectural diagrams, and things in general that make PDFs so much more valuable than mere text.</p>
<p>In this article, we'll show you a better way that not only retrieves the rich information embedded in charts, but also eliminates complex processing steps. We'll cover:</p>
<ul>
<li class=""><strong>Classic RAG</strong>: Why OCR and text embedding works great for some (structured and unstructured) data, but not for rich PDFs.</li>
<li class=""><strong>Late Interaction RAG</strong>: What late-interaction multi-vector models are, and why they let you skip text extraction entirely.</li>
<li class=""><strong>Drag-N-Drop and Done</strong>: How to ingest multiple PDFs in Weaviate Cloud with just a few clicks.</li>
<li class=""><strong>Real Examples</strong>: Example queries against NVIDIA's FY2026 quarterly earnings, where each top result is the <em>exact chart</em> that answers a question.</li>
<li class=""><strong>Complex Agentic Reasoning</strong>: How to wrap the same data with the Weaviate Query Agent for synthesised answers with page-image citations.</li>
<li class=""><strong>Codified and Deployment-Ready</strong>: The same ingestion pipeline in roughly 50 lines of Python for when you need to deploy this in production.</li>
</ul>
<p>If you'd rather just see the demo first and read the explanations later, skip to the queries section below.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="how-traditional-rag-falls-short">How traditional RAG falls short<a href="#how-traditional-rag-falls-short" class="hash-link" aria-label="Direct link to How traditional RAG falls short" title="Direct link to How traditional RAG falls short" translate="no">​</a></h2>
<p>Let's first look at what most people do today when it comes to building a RAG pipeline for PDFs:</p>
<ol>
<li class="">OCR (or text-extract) the file (using either a python library or third-party tooling).</li>
<li class="">Chunk the text.</li>
<li class="">Embed the chunks with a text embedding model.</li>
<li class="">Retrieve, (maybe) rerank, generate.</li>
</ol>
<p>There's nothing inherently bad about this workflow, but there's a naive underlying assumption that <em>the page can be reduced to a sequence of text tokens without losing the richness of the content</em>. For a press release or a Wikipedia article, this is mostly fine, but for a slide deck full of charts, a 10-K with comparison tables, or an academic paper with illustrative figures, it's simply not enough.</p>
<p>You could build a complex ETL pipeline to extract charts and vectorize them separately, but that means another model in the pipeline and introduces more complexity into the stack as well as merging problems at query time.</p>
<p>With a late-interaction multi-vector model, you don't need any of those: You embed the <em>page</em>, and not the text within it. The model sees the chart the way you do. Yes, you heard that right, there is not even a chunking step — the page <em>is</em> the chunk.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="late-interaction-multi-vector-retrieval-in-two-paragraphs">Late-interaction multi-vector retrieval, in two paragraphs<a href="#late-interaction-multi-vector-retrieval-in-two-paragraphs" class="hash-link" aria-label="Direct link to Late-interaction multi-vector retrieval, in two paragraphs" title="Direct link to Late-interaction multi-vector retrieval, in two paragraphs" translate="no">​</a></h2>
<p>Before we get to the demo, let's take a quick detour on what makes this work. If you already know your way around ColPali / ColBERT, feel free to skip or skim.</p>
<p>Traditional dense embedding models compress an entire document (or chunk) into a single vector. Late-interaction multi-vector models do something different: they encode the document as a <em>set</em> of vectors, typically one per token (or for a vision model like the one we're about to use, one per image patch). At query time, your query is also encoded as a set, and the relevance score is the sum of best matches between query tokens and document tokens (a quantity called MaxSim).</p>
<p>Instead of asking <em>"is this whole page about my whole question?"</em>, the model can ask <em>"is the part of this page that talks about Q4 FY26 a good match for the part of my question about 'change over time'?"</em>. For a chart-heavy page, this is exactly the granularity that's needed. The model doesn't have to summarise an entire slide into a single vector, but can keep one vector per region of the page, and the query can pick out the regions that matter.</p>
<p>So really, there are two distinct advantages here:</p>
<ol>
<li class="">Because it's a <strong>visual model</strong> you keep the layout, the charts, the tables, etc. <em>and</em></li>
<li class="">By using MaxSim over a set of vectors, you <strong>eliminate the need for chunking</strong>.</li>
</ol>
<p>Weaviate offers <code>multi2multivec-weaviate</code>, a vectorizer module that runs a hosted late-interaction multi-vector model on Weaviate Cloud, so you don't have to host or manage a model in order to generate multi-vectors from your PDFs.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="ingesting-pdfs-by-drag-and-drop">Ingesting PDFs by Drag-and-Drop<a href="#ingesting-pdfs-by-drag-and-drop" class="hash-link" aria-label="Direct link to Ingesting PDFs by Drag-and-Drop" title="Direct link to Ingesting PDFs by Drag-and-Drop" translate="no">​</a></h2>
<p>The fastest way to try this is the drag-and-drop importer in <a href="https://console.weaviate.cloud" target="_blank" rel="noopener noreferrer" class="">Weaviate Cloud</a>.</p>
<ol>
<li class="">Open your cluster in the Console.</li>
<li class="">Go to <em>Collections</em> and create a new collection.</li>
<li class="">Select the upload from file option and drop in your PDFs.</li>
</ol>
<div style="display:flex;gap:1rem;align-items:flex-start;margin:1.5rem 0"><div style="flex:1.5606 1 0"><a href="/assets/images/console-create-collection-90227cca6ba85195d4aa8c781acac4d5.png" target="_blank" rel="noopener noreferrer"><img src="/assets/images/console-create-collection-90227cca6ba85195d4aa8c781acac4d5.png" alt="Create new collection page in the Weaviate Console, with the Upload CSV, Excel or PDF option highlighted" style="width:100%;height:auto;display:block"></a></div><div style="flex:1.7175 1 0"><a href="/assets/images/console-upload-completed-4ff5dab338fa25e52498b3028da13c41.png" target="_blank" rel="noopener noreferrer"><img src="/assets/images/console-upload-completed-4ff5dab338fa25e52498b3028da13c41.png" alt="Weaviate Console after upload: a single NVIDIA Q4 FY26 PDF marked complete with a Next button" style="width:100%;height:auto;display:block"></a></div></div>
<p>And that's the entire ingestion process. Behind the scenes, Weaviate is doing three things:</p>
<ol>
<li class="">Rendering each PDF page to a high-resolution image.</li>
<li class="">Storing that image as a <code>BLOB</code> property on a new collection.</li>
<li class="">Vectorizing it with the <code>multi2multivec-weaviate</code> module, producing many vectors per page.</li>
</ol>
<p>A few things are worth noting:</p>
<ul>
<li class=""><strong>One object equals one page.</strong> The unit of retrieval is the page, which is also the unit a human navigates a document by.</li>
<li class=""><strong>No OCR.</strong> The model never sees the text as text. It sees the page as an image. That's why a chart with no caption is just as searchable as a paragraph.</li>
<li class=""><strong>The vectors are compressed.</strong> Late-interaction models can produce hundreds of vectors per page, which would be expensive to store naively. Weaviate uses a <a href="https://docs.weaviate.io/weaviate/configuration/compression/multi-vectors" target="_blank" rel="noopener noreferrer" class="">multi-vector encoding</a> scheme that keeps the index compact. (More on that also in the trade-offs section below.)</li>
</ul>
<p>For this demo, we've imported NVIDIA's four FY2026 quarterly investor presentations (Q1 through Q4). They cover the financial year ending in January 2026, contain wall-to-wall charts and tables, and total 92 pages. The whole import took about a minute and a half.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="interrogating-nvidias-quarterly-earnings">Interrogating NVIDIA's Quarterly Earnings<a href="#interrogating-nvidias-quarterly-earnings" class="hash-link" aria-label="Direct link to Interrogating NVIDIA's Quarterly Earnings" title="Direct link to Interrogating NVIDIA's Quarterly Earnings" translate="no">​</a></h2>
<p>Before we do anything fancy such as agentic reasoning on the data, we want to show you the raw retrieval results, as they are already impressive on their own.</p>
<p>With ingestion complete, you can query the data directly in the Console (or with any Weaviate client). The query is in plain English, and the result is a ranked list of pages with page images inline.</p>
<p>Let's walk through three queries and show you what results are returned.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="query-1-how-did-automotive-revenue-change-over-time">Query 1: <em>"how did automotive revenue change over time?"</em><a href="#query-1-how-did-automotive-revenue-change-over-time" class="hash-link" aria-label="Direct link to query-1-how-did-automotive-revenue-change-over-time" title="Direct link to query-1-how-did-automotive-revenue-change-over-time" translate="no">​</a></h3>
<p><img decoding="async" loading="lazy" alt="Top result for the automotive revenue query — a five-quarter bar chart from NVIDIA&amp;#39;s Q2 FY26 deck" src="/assets/images/nvidia-automotive-revenue-85faef4afeec10a9bf00e73a989fa32d.png" width="2000" height="1125" class="img_ev3q"></p>
<p>The top result is a single page from the Q2 FY26 deck, titled <em>Automotive</em>. The left half is a bar chart showing five quarters of revenue (<code>$346M → $449M → $570M → $567M → $586M</code>, +69% Y/Y). The right half contains three bullet points about <code>Thor SoC</code> and <code>DRIVE AV</code>.</p>
<p>The phrase <em>"over time"</em> doesn't appear anywhere on this page. Neither does the word <em>"change"</em>. The model didn't match against text semantically, but rather the image of the page. What it saw was five bars of increasing height with quarterly labels, and that was enough to identify the page as a match for a question about a temporal trend.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="query-2-gross-margin-trend">Query 2: <em>"gross margin trend"</em><a href="#query-2-gross-margin-trend" class="hash-link" aria-label="Direct link to query-2-gross-margin-trend" title="Direct link to query-2-gross-margin-trend" translate="no">​</a></h3>
<p><img decoding="async" loading="lazy" alt="Top result for the gross margin trend query — a combination chart with revenue bars and a gross margin line over five quarters, plus a financial KPI table" src="/assets/images/nvidia-gross-margin-trend-e0d7228ff81c186427895df91b474186.png" width="2000" height="1125" class="img_ev3q"></p>
<p>The top result here is the <em>Q2 FY26 Financial Summary</em> page. On the left is a combination chart: revenue bars and a non-GAAP gross margin line over five quarters. On the right is a GAAP/non-GAAP KPI table with Y/Y and Q/Q deltas.</p>
<p>Again, nothing on this page literally says "gross margin trend", but there <em>is</em> a line chart that visualises the gross margin dipping from 75.7% to 61.0% in Q1 FY26 and recovering to 72.7% in Q2 FY26. That's what a <em>trend</em> looks like, and it's what the model retrieved.</p>
<p>A side note: the same page also contains a detailed financial table. That makes it a particularly useful retrieval target if you're then going to ask follow-up questions like <em>"by how many basis points did gross margin recover Q/Q?"</em> The answer is sitting on the page the model already returned. More on that below when we introduce the Query Agent.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="query-3-how-did-data-center-revenue-change-over-time">Query 3: <em>"how did data center revenue change over time?"</em><a href="#query-3-how-did-data-center-revenue-change-over-time" class="hash-link" aria-label="Direct link to query-3-how-did-data-center-revenue-change-over-time" title="Direct link to query-3-how-did-data-center-revenue-change-over-time" translate="no">​</a></h3>
<p><img decoding="async" loading="lazy" alt="Top result for the data center revenue query — Q4 FY26 revenue page with a Y/Y bar chart and bullet points" src="/assets/images/nvidia-data-center-revenue-cba7e28113971072f98de56a2abcd759.png" width="2000" height="1125" class="img_ev3q"></p>
<p>The top result is the Q4 FY26 <em>Revenue</em> page — a Y/Y bar chart (<code>$39.3B → $68.1B</code>) with a callout that data center revenue is up 13x since the emergence of ChatGPT. This is a great example that the model still respects text when it's the better match. In this case the chart is less relevant, but the box stating the exact answer is what returned the highest similarity (MaxSim) on this page. So you get the best of both modalities.</p>
<p>The runner-up is the dedicated <em>Data Center</em> page from a different quarter, which splits the segment into Compute and Networking:</p>
<p><img decoding="async" loading="lazy" alt="Runner-up: Q3 FY26 Data Center page splitting the segment into Compute and Networking bar charts" src="/assets/images/nvidia-data-center-split-9df02586dbcfe9cd614253b520897560.png" width="2000" height="1125" class="img_ev3q"></p>
<p>Notice how the second-best match isn't simply <em>"another page about data center"</em>, but a different <em>kind</em> of answer — the same revenue, broken down differently. That's a useful property for an agent that wants to triangulate across multiple views of the same underlying number. Speaking of which...</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="from-search-to-answers-the-weaviate-query-agent">From search to answers: the Weaviate Query Agent<a href="#from-search-to-answers-the-weaviate-query-agent" class="hash-link" aria-label="Direct link to From search to answers: the Weaviate Query Agent" title="Direct link to From search to answers: the Weaviate Query Agent" translate="no">​</a></h2>
<p>Vector search returns results, but sometimes you want an answer.</p>
<p>The <a href="https://docs.weaviate.io/agents/query" target="_blank" rel="noopener noreferrer" class="">Weaviate Query Agent</a> is a managed agent that wraps vector retrieval with multi-step reasoning, source citations, and inline page images. It is available out of the box for any Weaviate Cloud cluster. Simply point it to a collection and ask a question.</p>
<p><img decoding="async" loading="lazy" alt="Weaviate Query Agent answering an automotive revenue question with a synthesised, multi-quarter response" src="/assets/images/query-agent-response-dba61844921e16001352d72e099f1cb2.png" width="3680" height="2382" class="img_ev3q"></p>
<p>If we ask <em>"How did automotive revenue change across FY26 quarters? What's driving it?"</em> about the same collection, the agent comes back with a synthesised answer (the numbers from the bar chart, plus the bullet points about <code>Thor SoC</code> and <code>DRIVE AV</code> adoption) and the underlying page images as citations. The agent decided which pages to retrieve, <em>looked</em> at them visually, and quoted directly from the slide.</p>
<div style="display:flex;gap:1.5rem;align-items:flex-start;margin:1.5rem 0"><div style="flex:1"><p>Open the <em>Sources</em> panel and you'll see exactly which pages backed the answer. Among the citations is the <em>Automotive</em> page from the Q1 FY26 deck — the same kind of bar chart we surfaced in the raw vector search earlier, just for a different quarter.</p><p>Every numerical claim in the response is anchored to a specific page in a specific PDF, with the page image right there for verification. You don't have to blindly trust the agent, but can read the contents of the slide for yourself.</p></div><img src="/assets/images/query-agent-sources-49cc33b2f9338242e692bbc5017195e3.png" alt="Sources panel from the Query Agent — the cited pages include the actual Automotive bar chart from the Q1 FY26 deck" style="width:40%;flex:0 0 40%;max-width:360px"></div>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="building-a-deployable-pipeline-with-python">Building a deployable pipeline with Python<a href="#building-a-deployable-pipeline-with-python" class="hash-link" aria-label="Direct link to Building a deployable pipeline with Python" title="Direct link to Building a deployable pipeline with Python" translate="no">​</a></h2>
<p>The drag-and-drop UI is the fastest path to creating a POC, but most production pipelines need code, and here is the equivalent in roughly 50 lines.</p>
<p>First, install the dependencies:</p>
<div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token plain">pip install "weaviate-client&gt;=4.21" PyMuPDF</span><br></span></code></pre></div></div>
<p>Then, render each PDF page to a 2000-pixel PNG and store it as a BLOB in a collection vectorized with <code>multi2multivec-weaviate</code>:</p>
<div class="language-python codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-python codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">import</span><span class="token plain"> os</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">from</span><span class="token plain"> base64 </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">import</span><span class="token plain"> b64encode</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">from</span><span class="token plain"> pathlib </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">import</span><span class="token plain"> Path</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">import</span><span class="token plain"> fitz  </span><span class="token comment" style="color:rgb(98, 114, 164)"># PyMuPDF</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">from</span><span class="token plain"> weaviate </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">import</span><span class="token plain"> connect_to_weaviate_cloud</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">from</span><span class="token plain"> weaviate</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">classes</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">config </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">import</span><span class="token plain"> Configure</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> DataType</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> Property</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">def</span><span class="token plain"> </span><span class="token function" style="color:rgb(80, 250, 123)">page_to_b64</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain">page</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> long_edge</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"> </span><span class="token builtin" style="color:rgb(189, 147, 249)">int</span><span class="token plain"> </span><span class="token operator">=</span><span class="token plain"> </span><span class="token number">2000</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token plain"> </span><span class="token operator">-</span><span class="token operator">&gt;</span><span class="token plain"> </span><span class="token builtin" style="color:rgb(189, 147, 249)">str</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    scale </span><span class="token operator">=</span><span class="token plain"> long_edge </span><span class="token operator">/</span><span class="token plain"> </span><span class="token builtin" style="color:rgb(189, 147, 249)">max</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain">page</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">rect</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">width</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> page</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">rect</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">height</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    pix </span><span class="token operator">=</span><span class="token plain"> page</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">get_pixmap</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain">matrix</span><span class="token operator">=</span><span class="token plain">fitz</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">Matrix</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain">scale</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> scale</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">return</span><span class="token plain"> b64encode</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain">pix</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">tobytes</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain">output</span><span class="token operator">=</span><span class="token string" style="color:rgb(255, 121, 198)">"png"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">decode</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">client </span><span class="token operator">=</span><span class="token plain"> connect_to_weaviate_cloud</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    os</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">environ</span><span class="token punctuation" style="color:rgb(248, 248, 242)">[</span><span class="token string" style="color:rgb(255, 121, 198)">"WEAVIATE_URL"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">]</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    auth_credentials</span><span class="token operator">=</span><span class="token plain">os</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">environ</span><span class="token punctuation" style="color:rgb(248, 248, 242)">[</span><span class="token string" style="color:rgb(255, 121, 198)">"WEAVIATE_API_KEY"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">]</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">if</span><span class="token plain"> </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">not</span><span class="token plain"> client</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">collections</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">exists</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token string" style="color:rgb(255, 121, 198)">"PDF"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    client</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">collections</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">create</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">        name</span><span class="token operator">=</span><span class="token string" style="color:rgb(255, 121, 198)">"PDF"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">        properties</span><span class="token operator">=</span><span class="token punctuation" style="color:rgb(248, 248, 242)">[</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">            Property</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain">name</span><span class="token operator">=</span><span class="token string" style="color:rgb(255, 121, 198)">"pdf_name"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> data_type</span><span class="token operator">=</span><span class="token plain">DataType</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">TEXT</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">            Property</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain">name</span><span class="token operator">=</span><span class="token string" style="color:rgb(255, 121, 198)">"page_number"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> data_type</span><span class="token operator">=</span><span class="token plain">DataType</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">INT</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">            Property</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain">name</span><span class="token operator">=</span><span class="token string" style="color:rgb(255, 121, 198)">"page_image"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> data_type</span><span class="token operator">=</span><span class="token plain">DataType</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">BLOB</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">        </span><span class="token punctuation" style="color:rgb(248, 248, 242)">]</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">        vector_config</span><span class="token operator">=</span><span class="token plain">Configure</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">MultiVectors</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">multi2vec_weaviate</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">            image_field</span><span class="token operator">=</span><span class="token string" style="color:rgb(255, 121, 198)">"page_image"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">        </span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    </span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">col </span><span class="token operator">=</span><span class="token plain"> client</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">collections</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">get</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token string" style="color:rgb(255, 121, 198)">"PDF"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">for</span><span class="token plain"> pdf_path </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">in</span><span class="token plain"> Path</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token string" style="color:rgb(255, 121, 198)">"pdfs"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">glob</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token string" style="color:rgb(255, 121, 198)">"*.pdf"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">with</span><span class="token plain"> col</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">batch</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">fixed_size</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain">batch_size</span><span class="token operator">=</span><span class="token number">2</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token plain"> </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">as</span><span class="token plain"> batch</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> fitz</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token builtin" style="color:rgb(189, 147, 249)">open</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain">pdf_path</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token plain"> </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">as</span><span class="token plain"> doc</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">        </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">for</span><span class="token plain"> i</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> page </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">in</span><span class="token plain"> </span><span class="token builtin" style="color:rgb(189, 147, 249)">enumerate</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain">doc</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> start</span><span class="token operator">=</span><span class="token number">1</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">            batch</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">add_object</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain">properties</span><span class="token operator">=</span><span class="token punctuation" style="color:rgb(248, 248, 242)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">                </span><span class="token string" style="color:rgb(255, 121, 198)">"pdf_name"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"> pdf_path</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">name</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">                </span><span class="token string" style="color:rgb(255, 121, 198)">"page_number"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"> i</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">                </span><span class="token string" style="color:rgb(255, 121, 198)">"page_image"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"> page_to_b64</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain">page</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">            </span><span class="token punctuation" style="color:rgb(248, 248, 242)">}</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">client</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">close</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><br></span></code></pre></div></div>
<p>A few notes on the above:</p>
<ul>
<li class=""><strong>The Python call <code>MultiVectors.multi2vec_weaviate(image_field="page_image")</code> configures the <code>multi2multivec-weaviate</code> module.</strong> This is the same vectorizer used by the Console import UI.</li>
<li class=""><strong><code>PyMuPDF</code> does the rasterization.</strong> The <code>2000</code> pixel long-edge target is a sensible default; smaller targets saves time while larger gives the model more detail. We haven't found a strong case for going below 1500 or above 2500.</li>
<li class=""><strong><code>batch_size=2</code> is intentional.</strong> Each object carries a multi-megabyte image, so small batches keep the gRPC payload sane.</li>
</ul>
<p>Query the created collection to return ranked pages:</p>
<div class="language-python codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-python codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">from</span><span class="token plain"> weaviate</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">classes</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">query </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">import</span><span class="token plain"> MetadataQuery</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">res </span><span class="token operator">=</span><span class="token plain"> col</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">query</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">near_text</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    query</span><span class="token operator">=</span><span class="token string" style="color:rgb(255, 121, 198)">"how did automotive revenue change over time"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    limit</span><span class="token operator">=</span><span class="token number">5</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    return_properties</span><span class="token operator">=</span><span class="token punctuation" style="color:rgb(248, 248, 242)">[</span><span class="token string" style="color:rgb(255, 121, 198)">"pdf_name"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> </span><span class="token string" style="color:rgb(255, 121, 198)">"page_number"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">]</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    return_metadata</span><span class="token operator">=</span><span class="token plain">MetadataQuery</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain">distance</span><span class="token operator">=</span><span class="token boolean">True</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">for</span><span class="token plain"> o </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">in</span><span class="token plain"> res</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">objects</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">print</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain">o</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">metadata</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">distance</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> o</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">properties</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><br></span></code></pre></div></div>
<p>On the NVIDIA corpus, this returns the Q2 FY26 <em>Automotive</em> page as result #1: the same five-quarter bar chart you saw above, retrieved by an end-to-end pipeline that contains zero OCR.</p>
<p>The same Query Agent you saw in the Console is also available from Python. Pass it the collections to reason over, then <code>ask()</code>:</p>
<div class="language-python codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-python codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">from</span><span class="token plain"> weaviate</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">agents</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">query </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">import</span><span class="token plain"> QueryAgent</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">from</span><span class="token plain"> weaviate_agents</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">classes </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">import</span><span class="token plain"> QueryAgentCollectionConfig</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">agent </span><span class="token operator">=</span><span class="token plain"> QueryAgent</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    client</span><span class="token operator">=</span><span class="token plain">client</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    collections</span><span class="token operator">=</span><span class="token punctuation" style="color:rgb(248, 248, 242)">[</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">        QueryAgentCollectionConfig</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain">name</span><span class="token operator">=</span><span class="token string" style="color:rgb(255, 121, 198)">"PDF"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    </span><span class="token punctuation" style="color:rgb(248, 248, 242)">]</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">response </span><span class="token operator">=</span><span class="token plain"> agent</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">ask</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token string" style="color:rgb(255, 121, 198)">"How did automotive revenue change across FY26 quarters? What's driving it?"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">response</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">display</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><br></span></code></pre></div></div>
<p><code>response.display()</code> renders the same synthesised answer plus page-image citations you saw in the Console.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="so-is-this-the-silver-bullet-for-pdfs">So is this the silver bullet for PDFs?<a href="#so-is-this-the-silver-bullet-for-pdfs" class="hash-link" aria-label="Direct link to So is this the silver bullet for PDFs?" title="Direct link to So is this the silver bullet for PDFs?" translate="no">​</a></h2>
<p>Of course not. As always in Engineering, there are trade-offs:</p>
<ul>
<li class=""><strong>Many vectors per object/page.</strong> Late-interaction multi-vector models produce many vectors per page. You can partially offset this with compression techniques, such as <a class="" href="/blog/muvera">Muvera</a>, which are natively supported in Weaviate. This helps, but also introduces a compression/accuracy trade-off. For a corpus that is dominated by large amounts of plain text (think legal contracts, transcripts, or log files), a text embedding model will still be cheaper and just as accurate.</li>
<li class=""><strong>Page-level retrieval is coarse.</strong> If your answer lives in one paragraph buried in a dense contract, returning a whole page may be more context than you want. In practice, we see this typically mitigated in the agent layer (e.g. Weaviate's Query agent), where the relevant paragraph can be identified without requiring a significant number of tokens.</li>
<li class=""><strong>The model has to understand your charts.</strong> It generalises well from the public corpora it was trained on, but if you have very domain-specific visual conventions (think highly stylised internal templates), you should validate retrieval quality on it first.</li>
</ul>
<p>So when does this approach with late-interaction multi-vector models win? Mostly in PDF-heavy domains that contain assets such as quarterly slide decks, due-diligence packets, scientific figures, and technical drawings, etc. For text-dominated corpora, a text pipeline is most likely cheaper and sufficiently performant.</p>
<p>For further optimization, you might consider using a hybrid approach, where you identify pages with charts to implement as multi-vectors and the remaining corpus as text, and then use an RRF-style approach to merge results at query time.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="conclusion">Conclusion<a href="#conclusion" class="hash-link" aria-label="Direct link to Conclusion" title="Direct link to Conclusion" translate="no">​</a></h2>
<p>Let's wrap up with the key takeaways:</p>
<ul>
<li class=""><strong>Charts and tables are not problems to be solved by better OCR.</strong> They are <em>primary information</em> that gets destroyed in extraction. If your pipeline only indexes text, valuable information from charts is already lost before you started embedding.</li>
<li class=""><strong>Late-interaction multi-vector models let you skip extraction entirely.</strong> Render the page, embed the image, and ask questions about what the image means. The model retrieves pages by what they look like --- charts, tables, layout, and all.</li>
<li class=""><strong>On Weaviate Cloud, ingestion is drag-and-drop.</strong> Point the Query Agent at the resulting collection, ask a question, and get an answer with proper images as citation.</li>
<li class=""><strong>Turn the same primitive into deployable code.</strong> <code>MultiVectors.multi2vec_weaviate(image_field="page_image")</code> is the entire vectorizer config. The rest is rasterising pages with PyMuPDF and a small <code>batch.add_object</code> loop.</li>
</ul>
<p>If you have been working around chart-heavy PDFs because the indexing pipeline made them too painful to deal with, this is worth a try. The kind of files you used to skip, because they were <em>"mostly charts"</em>, are exactly what this approach is built for.</p>
<p>Spin up a <a href="https://console.weaviate.cloud" target="_blank" rel="noopener noreferrer" class="">Weaviate Cloud</a> cluster, upload your PDFs, and start asking questions today.</p>
<!-- -->
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="ready-to-start-building">Ready to start building?<a href="#ready-to-start-building" class="hash-link" aria-label="Direct link to Ready to start building?" title="Direct link to Ready to start building?" translate="no">​</a></h2>
<p>Check out the <a href="https://docs.weaviate.io/weaviate/quickstart" target="_blank" rel="noopener noreferrer" class="">Quickstart tutorial</a>, or <a href="https://console.weaviate.cloud/?utm_source=blog&amp;utm_medium=website&amp;utm_campaign=blog_signup&amp;utm_content=charts-tables-pdfs&amp;utm_term=ready-to-start-building" target="_blank" rel="noopener noreferrer">sign up for a free Weaviate Cloud account</a>.</p>
<!-- -->
]]></content:encoded>
            <category>how-to</category>
            <category>search</category>
        </item>
        <item>
            <title><![CDATA[Weaviate 1.39 Release]]></title>
            <link>https://weaviate.io/blog/weaviate-1-39-release</link>
            <guid>https://weaviate.io/blog/weaviate-1-39-release</guid>
            <pubDate>Thu, 27 Aug 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[Weaviate 1.39 promotes the Boost API and MMR diversity selection to GA, previews 4-bit Rotational Quantization, and ships an experimental Search REST API.]]></description>
            <content:encoded><![CDATA[<p>Weaviate <code>v1.39</code> is now available open-source and on <a href="https://console.weaviate.cloud" target="_blank" rel="noopener noreferrer" class="">Weaviate Cloud</a>.</p>
<p>Two search features reach <strong>general availability</strong> in this release: the <strong>Boost API</strong> for query-time rescoring, and <strong>Maximal Marginal Relevance (MMR) diversity selection</strong>, which works on hybrid search as well as vector search. Two more are new: <strong>4-bit Rotational Quantization</strong> as a preview, and an experimental <strong>Search REST API</strong>. This post also covers <strong>gRPC-Web</strong>, which shipped quietly in the 1.38 line, and the <strong>HNSW snapshot</strong> rework, which cuts commit-log disk usage and speeds up startup.</p>
<p>Here are the release highlights!</p>
<p><img decoding="async" loading="lazy" alt="Weaviate 1.39 is released" src="/assets/images/hero-a412819ae697ef06bc71aff11e9f7f87.png" width="1200" height="630" class="img_ev3q"></p>
<ul>
<li class=""><a href="#boost-api---general-availability" class="">Boost API - General Availability</a></li>
<li class=""><a href="#mmr-diversity-selection---general-availability" class="">MMR Diversity Selection - General Availability</a></li>
<li class=""><a href="#4-bit-rotational-quantization-preview" class="">4-bit Rotational Quantization (Preview)</a></li>
<li class=""><a href="#search-rest-api-experimental" class="">Search REST API (Experimental)</a></li>
<li class=""><a href="#grpc-web" class="">gRPC-Web</a></li>
<li class=""><a href="#hnsw-snapshots-automatic---general-availability" class="">HNSW Snapshots, Automatic - General Availability</a></li>
<li class=""><a href="#performance-improvements-and-fixes" class="">Performance Improvements and Fixes</a></li>
<li class=""><a href="#community-contributions" class="">Community Contributions</a></li>
<li class=""><a href="#summary" class="">Summary</a></li>
</ul>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="boost-api---general-availability">Boost API - General Availability<a href="#boost-api---general-availability" class="hash-link" aria-label="Direct link to Boost API - General Availability" title="Direct link to Boost API - General Availability" translate="no">​</a></h2>
<p>The <a class="" href="/blog/weaviate-1-38-release#boost-api-preview">Boost API</a>, introduced as a preview in <code>v1.38</code>, is now <strong>generally available</strong>.</p>
<p>Boost is a query-time rescorer. After the primary search fetches its candidates, Weaviate scores each one against your boost conditions and re-sorts the list. Unlike a filter, it never removes anything: an object that matches nothing is demoted, not dropped. That is the difference between "only show me in-stock products" and "prefer in-stock products, but still show me the perfect match that is out of stock".</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="how-it-works">How it works<a href="#how-it-works" class="hash-link" aria-label="Direct link to How it works" title="Direct link to How it works" translate="no">​</a></h3>
<p>A boost holds between one and twenty conditions, and there are four kinds:</p>
<ul>
<li class=""><strong><code>filter</code></strong> promotes results that satisfy a filter</li>
<li class=""><strong><code>property_value</code></strong> ranks by a numeric property's value</li>
<li class=""><strong><code>time_decay</code></strong> favors objects near a point in time</li>
<li class=""><strong><code>numeric_decay</code></strong> favors objects near a target number</li>
</ul>
<p>Two weights control the result. The outer <code>weight</code> (default <code>0.5</code>) mixes the boost score into the original relevance score: <code>(1 - weight) * primary + weight * boost</code>. Each condition then carries its own <code>weight</code> (default <code>1.0</code>). Make that one <strong>negative</strong> if you want the condition to demote instead of promote.</p>
<p>A third setting, <code>depth</code> (default <code>100</code>, capped by <code>QUERY_MAXIMUM_RESULTS</code>), is how many candidates the primary search fetches before the re-sort. An operator can move that default for the whole cluster with <code>QUERY_BOOST_DEFAULT_DEPTH</code>.</p>
<p>Here is what that does to a real result page. The same query runs twice over a small product catalog: once plain, once with a boost that prefers products that are in stock and recently released:</p>
<div class="language-python codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-python codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">from</span><span class="token plain"> datetime </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">import</span><span class="token plain"> timedelta</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">from</span><span class="token plain"> weaviate</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">classes</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">query </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">import</span><span class="token plain"> Boost</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> Filter</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">prefer_in_stock_and_recent </span><span class="token operator">=</span><span class="token plain"> Boost</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">blend</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    </span><span class="token punctuation" style="color:rgb(248, 248, 242)">[</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">        Boost</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token builtin" style="color:rgb(189, 147, 249)">filter</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain">Filter</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">by_property</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token string" style="color:rgb(255, 121, 198)">"in_stock"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">equal</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token boolean">True</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> weight</span><span class="token operator">=</span><span class="token number">2.0</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">        Boost</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">time_decay</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token string" style="color:rgb(255, 121, 198)">"released"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> scale</span><span class="token operator">=</span><span class="token plain">timedelta</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain">days</span><span class="token operator">=</span><span class="token number">30</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    </span><span class="token punctuation" style="color:rgb(248, 248, 242)">]</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    weight</span><span class="token operator">=</span><span class="token number">0.3</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain">   </span><span class="token comment" style="color:rgb(98, 114, 164)"># 30% boost, 70% original relevance</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    depth</span><span class="token operator">=</span><span class="token number">200</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain">    </span><span class="token comment" style="color:rgb(98, 114, 164)"># re-score the top 200 candidates</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">for</span><span class="token plain"> label</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> boost </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">in</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token string" style="color:rgb(255, 121, 198)">"plain hybrid"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> </span><span class="token boolean">None</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token string" style="color:rgb(255, 121, 198)">"with boost"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> prefer_in_stock_and_recent</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    response </span><span class="token operator">=</span><span class="token plain"> collection</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">query</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">hybrid</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain">query</span><span class="token operator">=</span><span class="token string" style="color:rgb(255, 121, 198)">"wireless headphones"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> limit</span><span class="token operator">=</span><span class="token number">4</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> boost</span><span class="token operator">=</span><span class="token plain">boost</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">print</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain">label</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">for</span><span class="token plain"> obj </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">in</span><span class="token plain"> response</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">objects</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">        </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">print</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token string" style="color:rgb(255, 121, 198)">"  "</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> obj</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">properties</span><span class="token punctuation" style="color:rgb(248, 248, 242)">[</span><span class="token string" style="color:rgb(255, 121, 198)">"title"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">]</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> </span><span class="token string" style="color:rgb(255, 121, 198)">"| in stock:"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> obj</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">properties</span><span class="token punctuation" style="color:rgb(248, 248, 242)">[</span><span class="token string" style="color:rgb(255, 121, 198)">"in_stock"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">]</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><br></span></code></pre></div></div>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token plain">plain hybrid</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">   Kestrel Wireless Headphones | in stock: True</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">   Meridian Wireless Headphones | in stock: False</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">   Aurora Wireless Headphones | in stock: False</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">   Nimbus Wireless Headphones | in stock: True</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">with boost</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">   Kestrel Wireless Headphones | in stock: True</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">   Nimbus Wireless Headphones | in stock: True</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">   Wireless Earbuds Pro | in stock: True</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">   Meridian Wireless Headphones | in stock: False</span><br></span></code></pre></div></div>
<p>Nimbus is in stock and twelve days old, so it climbs from fourth to second. The earbuds take third for the same reason, even though the text match is weaker. The two out-of-stock listings lose ground: Meridian slides to fourth, and Aurora drops off the page. Neither one was removed from the result set. Kestrel, the best keyword and vector match, still holds first place. A <code>weight</code> of <code>0.3</code> leaves 70% of the score with the search itself. Raise it toward <code>1.0</code> and stock and freshness take over the ordering. Lower it toward <code>0.0</code> and you get the plain result back.</p>
<p>Boost is available on <code>hybrid</code>, <code>bm25</code>, <code>near_text</code>, <code>near_vector</code>, <code>near_object</code>, <code>near_media</code>, and <code>near_image</code>, in both the <code>.query.*</code> and <code>.generate.*</code> namespaces. It is not available on <code>fetch_objects</code>, which has no relevance score to blend with.</p>
<div class="theme-admonition theme-admonition-note admonition_xJq3 alert alert--secondary"><div class="admonitionHeading_Gvgb"><span class="admonitionIcon_Rf37"><svg viewBox="0 0 14 16"><path fill-rule="evenodd" d="M6.3 5.69a.942.942 0 0 1-.28-.7c0-.28.09-.52.28-.7.19-.18.42-.28.7-.28.28 0 .52.09.7.28.18.19.28.42.28.7 0 .28-.09.52-.28.7a1 1 0 0 1-.7.3c-.28 0-.52-.11-.7-.3zM8 7.99c-.02-.25-.11-.48-.31-.69-.2-.19-.42-.3-.69-.31H6c-.27.02-.48.13-.69.31-.2.2-.3.44-.31.69h1v3c.02.27.11.5.31.69.2.2.42.31.69.31h1c.27 0 .48-.11.69-.31.2-.19.3-.42.31-.69H8V7.98v.01zM7 2.3c-3.14 0-5.7 2.54-5.7 5.68 0 3.14 2.56 5.7 5.7 5.7s5.7-2.55 5.7-5.7c0-3.15-2.56-5.69-5.7-5.69v.01zM7 .98c3.86 0 7 3.14 7 7s-3.14 7-7 7-7-3.12-7-7 3.14-7 7-7z"></path></svg></span>Boost runs before a reranker</div><div class="admonitionContent_BuS1"><p>If you combine <code>boost=</code> with <code>rerank=</code>, the <a href="https://docs.weaviate.io/weaviate/search/rerank" target="_blank" rel="noopener noreferrer" class="">reranker</a> runs afterwards and re-sorts the boosted page, so it has the last word. Use one or the other unless you want that layering.</p></div></div>
<div class="theme-admonition theme-admonition-info admonition_xJq3 alert alert--info"><div class="admonitionHeading_Gvgb"><span class="admonitionIcon_Rf37"><svg viewBox="0 0 14 16"><path fill-rule="evenodd" d="M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"></path></svg></span>Related resources</div><div class="admonitionContent_BuS1"><ul>
<li class=""><a href="https://docs.weaviate.io/weaviate/search/boost" target="_blank" rel="noopener noreferrer" class="">How-to: Search - Boost results</a></li>
<li class=""><a href="https://docs.weaviate.io/weaviate/search/boost#blending-and-weights" target="_blank" rel="noopener noreferrer" class="">How-to: Search - Blending and weights</a></li>
</ul></div></div>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="mmr-diversity-selection---general-availability">MMR Diversity Selection - General Availability<a href="#mmr-diversity-selection---general-availability" class="hash-link" aria-label="Direct link to MMR Diversity Selection - General Availability" title="Direct link to MMR Diversity Selection - General Availability" translate="no">​</a></h2>
<p><a class="" href="/blog/weaviate-1-37-release#diversity-search-with-mmr-preview">MMR diversity selection</a>, a preview since <code>v1.37</code>, is now <strong>generally available</strong>. It works on hybrid search alongside every <code>near_*</code> search. Hybrid support is not new in <code>v1.39</code>: it landed in <code>v1.38.6</code>, so if you are on a recent 1.38 patch you already have it. What <code>v1.39</code> changes is the maturity label.</p>
<p>MMR picks results one at a time. At each step it weighs two things: how well a candidate matches the query, and how different it is from the results already picked. You end up with a first page that covers the topic instead of showing the same passage nine times. That helps most in <a class="" href="/blog/hybrid-search-explained">hybrid search</a>. The keyword half and the vector half of a hybrid query tend to agree on the same cluster of near-identical chunks, so their merged top 10 is often the most repetitive list in your system.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="how-it-works-1">How it works<a href="#how-it-works-1" class="hash-link" aria-label="Direct link to How it works" title="Direct link to How it works" translate="no">​</a></h3>
<p>MMR runs near the end of the query pipeline, after the two halves are merged and before the page is cut. A reranker, if you use one, runs after MMR:</p>
<!-- -->
<p>Two values configure it, and both are easy to get backwards.</p>
<p><strong><code>balance</code></strong> trades relevance against diversity. It takes a value from <code>0.0</code> to <code>1.0</code>, and anything outside that range is rejected with <code>MMR balance must be between 0 and 1</code>. At <code>1.0</code> you get <strong>pure relevance</strong>, which is the same order you would get without MMR. At <code>0.0</code> you get <strong>pure diversity</strong>. So <strong>lower means more diverse</strong>. The default is <code>0.0</code>, not <code>0.5</code>. Leave <code>balance</code> out and you get the most aggressive setting there is, so always pass it explicitly.</p>
<p><strong><code>limit</code></strong> on the MMR selection is your <strong>page size</strong>, the number of results you get back. MMR picks those results out of a candidate pool, and the pool is the query's own <code>limit</code>. The MMR limit must be at least 1 and no larger than the query limit.</p>
<p>Here is the same query at three settings. The collection holds documentation chunks, and four of them say roughly the same thing about carbon pricing:</p>
<div class="language-python codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-python codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">from</span><span class="token plain"> weaviate</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">classes</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">query </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">import</span><span class="token plain"> Diversity</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">for</span><span class="token plain"> balance </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">in</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token number">1.0</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> </span><span class="token number">0.3</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> </span><span class="token number">0.0</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    response </span><span class="token operator">=</span><span class="token plain"> collection</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">query</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">hybrid</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">        query</span><span class="token operator">=</span><span class="token string" style="color:rgb(255, 121, 198)">"carbon pricing"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">        limit</span><span class="token operator">=</span><span class="token number">8</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain">                                                      </span><span class="token comment" style="color:rgb(98, 114, 164)"># candidate pool</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">        diversity_selection</span><span class="token operator">=</span><span class="token plain">Diversity</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">mmr</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain">limit</span><span class="token operator">=</span><span class="token number">4</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> balance</span><span class="token operator">=</span><span class="token plain">balance</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain">  </span><span class="token comment" style="color:rgb(98, 114, 164)"># 4 returned</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    </span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">print</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token string-interpolation string" style="color:rgb(255, 121, 198)">f"balance=</span><span class="token string-interpolation interpolation punctuation" style="color:rgb(248, 248, 242)">{</span><span class="token string-interpolation interpolation">balance</span><span class="token string-interpolation interpolation punctuation" style="color:rgb(248, 248, 242)">}</span><span class="token string-interpolation string" style="color:rgb(255, 121, 198)">"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">for</span><span class="token plain"> obj </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">in</span><span class="token plain"> response</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">objects</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">        </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">print</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token string" style="color:rgb(255, 121, 198)">"  "</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> obj</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">properties</span><span class="token punctuation" style="color:rgb(248, 248, 242)">[</span><span class="token string" style="color:rgb(255, 121, 198)">"title"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">]</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><br></span></code></pre></div></div>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token plain">balance=1.0</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">   Carbon tax versus cap and trade</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">   Carbon pricing basics</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">   Carbon pricing FAQ</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">   What is a carbon price?</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">balance=0.3</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">   Carbon tax versus cap and trade</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">   Carbon pricing FAQ</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">   Carbon pricing basics</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">   Adaptation funding for coastal cities</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">balance=0.0</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">   Carbon tax versus cap and trade</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">   Methane rules for oil and gas</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">   Adaptation funding for coastal cities</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">   Renewable subsidies and grid buildout</span><br></span></code></pre></div></div>
<p>At <code>1.0</code> the page is four ways of saying the same thing, which is the page you get without MMR. At <code>0.3</code> one of the duplicates gives up its slot to a chunk on adaptation funding. At <code>0.0</code> relevance stops counting after the first pick, and a carbon-pricing query comes back with methane rules and grid buildout. That last one is what you get if you leave <code>balance</code> out.</p>
<p>You need Python client <strong>4.23.0</strong> or newer. That is the release where <code>diversity_selection</code> arrives on <code>collection.query.hybrid</code> and <code>collection.generate.hybrid</code>. MMR is not available on <code>bm25</code>, which has no vectors to measure distance between, and it does not work on multi-vector collections.</p>
<div class="theme-admonition theme-admonition-info admonition_xJq3 alert alert--info"><div class="admonitionHeading_Gvgb"><span class="admonitionIcon_Rf37"><svg viewBox="0 0 14 16"><path fill-rule="evenodd" d="M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"></path></svg></span>Related resources</div><div class="admonitionContent_BuS1"><ul>
<li class=""><a href="https://docs.weaviate.io/weaviate/search/similarity#diversity-selection-mmr" target="_blank" rel="noopener noreferrer" class="">How-to: Search - Diversity selection (MMR)</a></li>
<li class=""><a href="https://docs.weaviate.io/weaviate/search/hybrid#diversity-selection-mmr" target="_blank" rel="noopener noreferrer" class="">How-to: Hybrid search - Diversity selection (MMR)</a></li>
<li class=""><a class="" href="/blog/hybrid-search-explained">Blog: Hybrid search explained</a></li>
</ul></div></div>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="4-bit-rotational-quantization-preview">4-bit Rotational Quantization (Preview)<a href="#4-bit-rotational-quantization-preview" class="hash-link" aria-label="Direct link to 4-bit Rotational Quantization (Preview)" title="Direct link to 4-bit Rotational Quantization (Preview)" translate="no">​</a></h2>
<p><a href="https://docs.weaviate.io/weaviate/concepts/vector-quantization#rotational-quantization" target="_blank" rel="noopener noreferrer" class="">Rotational quantization (RQ)</a> shrinks vectors in two steps. First it rotates the vector so the values spread evenly across the dimensions. Then it stores each dimension as a small integer code instead of a 32-bit float. Weaviate already ships 8-bit and 1-bit RQ. <code>v1.39</code> adds a <strong>4-bit</strong> width as a preview.</p>
<p>Four bits is half a byte, so two dimensions pack into one byte. At 1536 dimensions that is a 16-byte header plus 768 bytes of codes: <strong>784 bytes per vector</strong>, against 6144 bytes for raw <code>float32</code>. That is <strong>7.84x</strong> smaller, not a round "8x", because the header stays.</p>
<p>The general form is <code>16 + ceil(outputDim / 2)</code> bytes, where <code>outputDim = 64 * ceil(inputDim / 64)</code>. The rotation rounds your dimension count up to the next multiple of 64. At 1536 that round-up is free, because 1536 is 24 x 64. At 1000 dimensions it is not: you pay for 1024.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="how-it-works-2">How it works<a href="#how-it-works-2" class="hash-link" aria-label="Direct link to How it works" title="Direct link to How it works" translate="no">​</a></h3>
<p>There is no preview flag to unlock. It is a plain schema value, <code>rq.bits = 4</code>, on a vector index:</p>
<div class="language-python codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-python codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">from</span><span class="token plain"> weaviate</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">classes</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">config </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">import</span><span class="token plain"> Configure</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">client</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">collections</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">create</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    </span><span class="token string" style="color:rgb(255, 121, 198)">"Doc"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    vector_config</span><span class="token operator">=</span><span class="token plain">Configure</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">Vectors</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">text2vec_weaviate</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">        name</span><span class="token operator">=</span><span class="token string" style="color:rgb(255, 121, 198)">"default"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">        source_properties</span><span class="token operator">=</span><span class="token punctuation" style="color:rgb(248, 248, 242)">[</span><span class="token string" style="color:rgb(255, 121, 198)">"title"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> </span><span class="token string" style="color:rgb(255, 121, 198)">"body"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">]</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">        vector_index_config</span><span class="token operator">=</span><span class="token plain">Configure</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">VectorIndex</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">hnsw</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">            quantizer</span><span class="token operator">=</span><span class="token plain">Configure</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">VectorIndex</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">Quantizer</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">rq</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">                bits</span><span class="token operator">=</span><span class="token number">4</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">                rescore_limit</span><span class="token operator">=</span><span class="token number">20</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">            </span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">        </span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    </span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><br></span></code></pre></div></div>
<p><code>bits</code> is fixed the moment RQ is first enabled on a vector, and you cannot change it later. There is no migration from 8-bit codes to 4-bit codes, so pick the width when you create the collection.</p>
<p>If you would rather not set it per collection, an operator can make it the cluster-wide default for new vector indexes with <code>DEFAULT_QUANTIZATION=rq-4</code>. A new HNSW index then comes up with <code>bits: 4</code> and a <code>rescoreLimit</code> of <code>20</code>. Flat indexes are left alone.</p>
<div class="theme-admonition theme-admonition-caution admonition_xJq3 alert alert--warning"><div class="admonitionHeading_Gvgb"><span class="admonitionIcon_Rf37"><svg viewBox="0 0 16 16"><path fill-rule="evenodd" d="M8.893 1.5c-.183-.31-.52-.5-.887-.5s-.703.19-.886.5L.138 13.499a.98.98 0 0 0 0 1.001c.193.31.53.501.886.501h13.964c.367 0 .704-.19.877-.5a1.03 1.03 0 0 0 .01-1.002L8.893 1.5zm.133 11.497H6.987v-2.003h2.039v2.003zm0-3.004H6.987V5.987h2.039v4.006z"></path></svg></span>4-bit is HNSW-only</div><div class="admonitionContent_BuS1"><p>The flat index still rejects it with <code>RQ bits must be either 1 or 8</code>, and that applies to the flat side of a dynamic index too. Use <code>bits: 4</code> on an HNSW index.</p></div></div>
<p>Like the other RQ widths, 4-bit works with the <code>cosine</code>, <code>dot</code>, and <code>l2-squared</code> distance metrics.</p>
<div class="theme-admonition theme-admonition-caution admonition_xJq3 alert alert--warning"><div class="admonitionHeading_Gvgb"><span class="admonitionIcon_Rf37"><svg viewBox="0 0 16 16"><path fill-rule="evenodd" d="M8.893 1.5c-.183-.31-.52-.5-.887-.5s-.703.19-.886.5L.138 13.499a.98.98 0 0 0 0 1.001c.193.31.53.501.886.501h13.964c.367 0 .704-.19.877-.5a1.03 1.03 0 0 0 .01-1.002L8.893 1.5zm.133 11.497H6.987v-2.003h2.039v2.003zm0-3.004H6.987V5.987h2.039v4.006z"></path></svg></span>Preview</div><div class="admonitionContent_BuS1"><p>The 4-bit width is a <strong>preview</strong> feature. Its behavior and defaults may change in future releases.</p></div></div>
<div class="theme-admonition theme-admonition-info admonition_xJq3 alert alert--info"><div class="admonitionHeading_Gvgb"><span class="admonitionIcon_Rf37"><svg viewBox="0 0 14 16"><path fill-rule="evenodd" d="M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"></path></svg></span>Related resources</div><div class="admonitionContent_BuS1"><ul>
<li class=""><a href="https://docs.weaviate.io/weaviate/concepts/vector-quantization#rotational-quantization" target="_blank" rel="noopener noreferrer" class="">Concepts: Vector quantization - Rotational quantization</a></li>
<li class=""><a href="https://docs.weaviate.io/weaviate/concepts/vector-quantization#rescoring" target="_blank" rel="noopener noreferrer" class="">Concepts: Vector quantization - Rescoring</a></li>
<li class=""><a href="https://docs.weaviate.io/weaviate/config-refs/indexing/vector-index" target="_blank" rel="noopener noreferrer" class="">Config references: Vector index parameters</a></li>
</ul></div></div>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="search-rest-api-experimental">Search REST API (Experimental)<a href="#search-rest-api-experimental" class="hash-link" aria-label="Direct link to Search REST API (Experimental)" title="Direct link to Search REST API (Experimental)" translate="no">​</a></h2>
<p>Weaviate has two search APIs today. gRPC is fast, but it wants a generated client and HTTP/2. GraphQL means building a query string by hand and digging metadata out of <code>_additional</code>. Neither is pleasant from a shell script, a Lambda, an edge worker, an API gateway, or a language with no Weaviate client.</p>
<p><code>v1.39</code> adds an <strong>experimental Search REST API</strong>. You post JSON over plain HTTP/1.1 and get JSON back, and the endpoints are described by the OpenAPI spec like the rest of the REST API. That also suits LLM tool calling, where a model needs a documented HTTP endpoint rather than a client library.</p>
<p><code>v1.39.0</code> shipped one endpoint, <code>POST /v1/search/{collection}/near-text</code>. The <code>v1.39.1</code> patch added three more search endpoints and a matching aggregate endpoint, so on <code>1.39.1</code> or newer you get <a href="https://docs.weaviate.io/weaviate/api/rest#tag/search" target="_blank" rel="noopener noreferrer" class="">all five</a>:</p>
<ul>
<li class=""><code>POST /v1/search/{collection}/near-text</code></li>
<li class=""><code>POST /v1/search/{collection}/bm25</code></li>
<li class=""><code>POST /v1/search/{collection}/hybrid</code></li>
<li class=""><code>POST /v1/search/{collection}/near-object</code></li>
<li class=""><code>POST /v1/aggregate/{collection}</code></li>
</ul>
<p>The examples below use <code>near-text</code>.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="how-it-works-3">How it works<a href="#how-it-works-3" class="hash-link" aria-label="Direct link to How it works" title="Direct link to How it works" translate="no">​</a></h3>
<p>The endpoints are <strong>off by default</strong>. Turn them on per node with <a href="https://docs.weaviate.io/deploy/configuration/env-vars#EXPERIMENTAL_REST_SEARCH_ENABLED" target="_blank" rel="noopener noreferrer" class=""><code>EXPERIMENTAL_REST_SEARCH_ENABLED</code></a>:</p>
<div class="language-yaml codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-yaml codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token key atrule">services</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">  </span><span class="token key atrule">weaviate</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    </span><span class="token key atrule">image</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"> cr.weaviate.io/semitechnologies/weaviate</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain">1.39.1</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    </span><span class="token key atrule">environment</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">      </span><span class="token key atrule">EXPERIMENTAL_REST_SEARCH_ENABLED</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"> </span><span class="token string" style="color:rgb(255, 121, 198)">'true'</span><br></span></code></pre></div></div>
<p>Accepted truthy values are <code>on</code>, <code>enabled</code>, <code>1</code>, and <code>true</code>. One switch covers every endpoint in the set. When the feature is off, the routes are still there. They answer <code>422</code> with a message naming the variable to set, instead of a confusing <code>404</code>.</p>
<p>The request body is all camelCase. For <code>near-text</code>, <code>query</code> is a <strong>required array of strings</strong>, and each string is a piece of text to search for. Send one string for an ordinary search. Send several and Weaviate averages them into a single search vector. You can also send <code>certainty</code> or <code>distance</code> (not both), <code>targetVector</code>, <code>where</code>, <code>limit</code>, <code>offset</code>, <code>autoLimit</code>, <code>returnProperties</code>, <code>returnMetadata</code>, <code>tenant</code>, and <code>consistencyLevel</code>.</p>
<div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token plain">curl -s -X POST http://localhost:8080/v1/search/Movie/near-text \</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">  -H 'Content-Type: application/json' \</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">  -d '{"query":["spaceship galaxy"],"limit":3,</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">       "returnProperties":["title","hasAuthor.name"],</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">       "returnMetadata":["distance"]}'</span><br></span></code></pre></div></div>
<p>The response is <code>{results, tookMs}</code>. Every hit comes back in the same flat shape, <code>{id, properties, references, metadata}</code>:</p>
<div class="language-json codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-json codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token punctuation" style="color:rgb(248, 248, 242)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">  </span><span class="token property">"results"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">[</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    </span><span class="token punctuation" style="color:rgb(248, 248, 242)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">      </span><span class="token property">"id"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:rgb(255, 121, 198)">"2aeb3309-33e7-4a8d-a8e2-6413b53890d8"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">      </span><span class="token property">"properties"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">{</span><span class="token plain"> </span><span class="token property">"title"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:rgb(255, 121, 198)">"spaceship galaxy adventure"</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">}</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">      </span><span class="token property">"references"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">{</span><span class="token plain"> </span><span class="token property">"hasAuthor"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">[</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">{</span><span class="token plain"> </span><span class="token property">"name"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:rgb(255, 121, 198)">"famous writer"</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">}</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">]</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">}</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">      </span><span class="token property">"metadata"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">{</span><span class="token plain"> </span><span class="token property">"distance"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token number">0.07182336</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    </span><span class="token punctuation" style="color:rgb(248, 248, 242)">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">  </span><span class="token punctuation" style="color:rgb(248, 248, 242)">]</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">  </span><span class="token property">"tookMs"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token number">2</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token punctuation" style="color:rgb(248, 248, 242)">}</span><br></span></code></pre></div></div>
<p><code>references</code> is left out when your query does not read across a reference, and <code>metadata</code> is left out when you asked for nothing beyond the id. Vectors are never returned.</p>
<p>On errors you get the standard <code>{"error": [{"message": "..."}]}</code> body.</p>
<div class="theme-admonition theme-admonition-caution admonition_xJq3 alert alert--warning"><div class="admonitionHeading_Gvgb"><span class="admonitionIcon_Rf37"><svg viewBox="0 0 16 16"><path fill-rule="evenodd" d="M8.893 1.5c-.183-.31-.52-.5-.887-.5s-.703.19-.886.5L.138 13.499a.98.98 0 0 0 0 1.001c.193.31.53.501.886.501h13.964c.367 0 .704-.19.877-.5a1.03 1.03 0 0 0 .01-1.002L8.893 1.5zm.133 11.497H6.987v-2.003h2.039v2.003zm0-3.004H6.987V5.987h2.039v4.006z"></path></svg></span>Experimental means the shape can still change</div><div class="admonitionContent_BuS1"><p>This API is off by default, and its request and response shape is not frozen. Reference selection is the most likely part to change. In <code>v1.39</code> you ask for a referenced property by writing it with a dot inside <code>returnProperties</code>, one level deep, such as <code>"hasAuthor.name"</code>. That form is being replaced, so expect to update anything you build on it today.</p></div></div>
<p>No official client wraps this endpoint yet. Every Weaviate client speaks gRPC for search, so <code>curl</code> or raw HTTP is how you reach it for now. Boost, MMR, reranking, generative search, and group-by are not available over REST.</p>
<div class="theme-admonition theme-admonition-info admonition_xJq3 alert alert--info"><div class="admonitionHeading_Gvgb"><span class="admonitionIcon_Rf37"><svg viewBox="0 0 14 16"><path fill-rule="evenodd" d="M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"></path></svg></span>Related resources</div><div class="admonitionContent_BuS1"><ul>
<li class=""><a href="https://docs.weaviate.io/weaviate/api/rest#tag/search" target="_blank" rel="noopener noreferrer" class="">References: RESTful API - Search endpoints</a></li>
<li class=""><a href="https://docs.weaviate.io/deploy/configuration/env-vars#EXPERIMENTAL_REST_SEARCH_ENABLED" target="_blank" rel="noopener noreferrer" class="">Environment variables: <code>EXPERIMENTAL_REST_SEARCH_ENABLED</code></a></li>
</ul></div></div>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="grpc-web">gRPC-Web<a href="#grpc-web" class="hash-link" aria-label="Direct link to gRPC-Web" title="Direct link to gRPC-Web" translate="no">​</a></h2>
<p>Browsers cannot speak plain gRPC, so front-end code has never been able to call Weaviate's gRPC API directly. <strong>gRPC-Web</strong> closes that gap by serving the same API over ordinary HTTP. It arrived in <code>v1.38.3</code> and has not been covered in a release post until now.</p>
<p>The interface lives under the <code>/v1/grpc-web/</code> path prefix on the <strong>same port as the REST API</strong> (default <code>8080</code>). It is not on the gRPC port and not on a port of its own, so there is no second port to open in a firewall or an ingress rule.</p>
<p>It is <strong>enabled by default</strong>. To turn it off, set the <a href="https://docs.weaviate.io/deploy/configuration/env-vars/runtime-config" target="_blank" rel="noopener noreferrer" class="">runtime-configuration</a> key <code>grpc_web_enabled</code> to <code>false</code>. The key is snake_case, and it has no environment-variable equivalent. The change takes effect without a restart. While the interface is off, a request to a <code>/v1/grpc-web/</code> path comes back as a plain <code>404</code>, the same as any other path Weaviate does not serve. The rest of the REST API is unaffected.</p>
<p>One caveat: the Weaviate client libraries all connect over plain gRPC today, so none of them uses this interface yet.</p>
<div class="theme-admonition theme-admonition-info admonition_xJq3 alert alert--info"><div class="admonitionHeading_Gvgb"><span class="admonitionIcon_Rf37"><svg viewBox="0 0 14 16"><path fill-rule="evenodd" d="M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"></path></svg></span>Related resources</div><div class="admonitionContent_BuS1"><ul>
<li class=""><a href="https://docs.weaviate.io/weaviate/api/grpc#grpc-web" target="_blank" rel="noopener noreferrer" class="">References: gRPC API - gRPC-Web</a></li>
</ul></div></div>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="hnsw-snapshots-automatic---general-availability">HNSW Snapshots, Automatic - General Availability<a href="#hnsw-snapshots-automatic---general-availability" class="hash-link" aria-label="Direct link to HNSW Snapshots, Automatic - General Availability" title="Direct link to HNSW Snapshots, Automatic - General Availability" translate="no">​</a></h2>
<p>An HNSW index is rebuilt on startup by replaying its commit log, the append-only write-ahead log that records every change to the graph. A <em>snapshot</em> is a compacted image of that graph, so startup can load one file instead of replaying millions of records. Until now the snapshot was an optional cache: you scheduled it with a handful of environment variables, and the log it summarized stayed on disk forever. You paid for the same graph twice.</p>
<p>In <code>v1.39</code> snapshots are automatic and <strong>generally available</strong>. Weaviate writes and refreshes them in the background, and once a new snapshot is safely on disk it <strong>deletes every commit log that snapshot covers</strong>. What you get:</p>
<ul>
<li class=""><strong>Less disk.</strong> You keep the snapshot plus the writes made since it, instead of the snapshot plus the full history. On vector-heavy clusters that is most of the win.</li>
<li class=""><strong>Faster, steadier startup.</strong> Loading a snapshot takes about the same time on every restart. Replaying a log that only ever grows does not.</li>
<li class=""><strong>Nothing to tune.</strong> There are no snapshot environment variables and no schedule to set. Weaviate decides when to write the next one.</li>
</ul>
<p>Two things to know about the disk savings. The cleanup only runs on shards that are <strong>loaded</strong>, so an inactive tenant keeps its old files until the next time you use it. And disk usage goes <strong>up</strong> for a while during a snapshot, because Weaviate writes the new file before it deletes the old ones. Keep the headroom you have today.</p>
<p>Five settings that used to control snapshotting are now <strong>ignored</strong>. Weaviate still accepts them, and they will be removed in a future version:</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token plain">PERSISTENCE_HNSW_DISABLE_SNAPSHOTS</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">PERSISTENCE_HNSW_SNAPSHOT_INTERVAL_SECONDS</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">PERSISTENCE_HNSW_SNAPSHOT_ON_STARTUP</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">PERSISTENCE_HNSW_SNAPSHOT_MIN_DELTA_COMMITLOGS_NUMBER</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">PERSISTENCE_HNSW_SNAPSHOT_MIN_DELTA_COMMITLOGS_SIZE_PERCENTAGE</span><br></span></code></pre></div></div>
<p>Setting any of them logs a one-line warning at startup instead of failing, so an upgrade will not break on a stale config file. Delete them when it suits you. One HNSW persistence setting survives: <a href="https://docs.weaviate.io/deploy/configuration/env-vars#PERSISTENCE_HNSW_MAX_LOG_SIZE" target="_blank" rel="noopener noreferrer" class=""><code>PERSISTENCE_HNSW_MAX_LOG_SIZE</code></a> (default <code>500MiB</code>). It sets the write-ahead-log rotation size, not anything about snapshots, and it still applies.</p>
<div class="theme-admonition theme-admonition-info admonition_xJq3 alert alert--info"><div class="admonitionHeading_Gvgb"><span class="admonitionIcon_Rf37"><svg viewBox="0 0 14 16"><path fill-rule="evenodd" d="M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"></path></svg></span>Related resources</div><div class="admonitionContent_BuS1"><ul>
<li class=""><a href="https://docs.weaviate.io/weaviate/concepts/storage#hnsw-snapshots" target="_blank" rel="noopener noreferrer" class="">Concepts: Storage - HNSW snapshots</a></li>
<li class=""><a href="https://docs.weaviate.io/deploy/configuration/env-vars#PERSISTENCE_HNSW_MAX_LOG_SIZE" target="_blank" rel="noopener noreferrer" class="">Environment variables: <code>PERSISTENCE_HNSW_MAX_LOG_SIZE</code></a></li>
</ul></div></div>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="performance-improvements-and-fixes">Performance Improvements and Fixes<a href="#performance-improvements-and-fixes" class="hash-link" aria-label="Direct link to Performance Improvements and Fixes" title="Direct link to Performance Improvements and Fixes" translate="no">​</a></h2>
<p>Beyond the headline features, <code>v1.39</code> ships a long list of improvements. A few worth calling out:</p>
<ul>
<li class=""><strong>Faster keyword search:</strong> <code>bm25</code> queries, and the keyword half of <code>hybrid</code>, come back sooner after a round of work on the scoring path.</li>
<li class=""><strong>Cross-property keyword <code>AND</code>:</strong> a new <code>AndCross</code> search operator asks for every query term to appear somewhere on the object, rather than all of them inside one property. It shipped in the 1.38 line, and it is opt-in, so plain <code>And</code> keeps the behavior you have today.</li>
<li class=""><strong>Cheaper async replication:</strong> background repair does less redundant work on clusters with many tenants. Fixes stop deleted objects from coming back during a first scan, stop a repair from overwriting a newer local write, and stop a tenant shutdown from leaking memory.</li>
<li class=""><strong>Leaner HFresh:</strong> the HFresh vector index uses less memory and writes to disk less often.</li>
<li class=""><strong>More reliable backups:</strong> listing a backup on Azure no longer scans every object, a restore no longer forces lazy-loaded shards to load, and you can now set how many files an incremental backup deduplicates.</li>
<li class=""><strong>Safer replica movement:</strong> moving a replica between nodes now uses hard links, so it no longer pauses compaction. Schema changes that would clash with a move in flight are rejected, and two copy operations on the same shard no longer trip over each other.</li>
<li class=""><strong>Latency metrics below a millisecond:</strong> the HTTP and gRPC request-duration histograms now have buckets down to 100µs, so fast queries no longer all land in one bucket.</li>
<li class=""><strong>Batch delete returns 422:</strong> a batch delete with missing match fields now answers <code>422 Unprocessable Entity</code> instead of <code>500</code>.</li>
</ul>
<div class="theme-admonition theme-admonition-info admonition_xJq3 alert alert--info"><div class="admonitionHeading_Gvgb"><span class="admonitionIcon_Rf37"><svg viewBox="0 0 14 16"><path fill-rule="evenodd" d="M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"></path></svg></span>Related resources</div><div class="admonitionContent_BuS1"><ul>
<li class=""><a href="https://github.com/weaviate/weaviate/releases/tag/v1.39.0" target="_blank" rel="noopener noreferrer" class="">Weaviate 1.39: GitHub Release Notes</a></li>
</ul></div></div>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="community-contributions">Community Contributions<a href="#community-contributions" class="hash-link" aria-label="Direct link to Community Contributions" title="Direct link to Community Contributions" translate="no">​</a></h2>
<p>Weaviate is open source, and this release includes work from five first-time contributors. Thank you to:</p>
<ul>
<li class=""><a href="https://github.com/hashkanna" target="_blank" rel="noopener noreferrer" class="">@hashkanna</a>: location configuration for the <code>text2vec-google</code> module (<a href="https://github.com/weaviate/weaviate/pull/8418" target="_blank" rel="noopener noreferrer" class="">#8418</a>)</li>
<li class=""><a href="https://github.com/vjsai" target="_blank" rel="noopener noreferrer" class="">@vjsai</a>: rejecting a negative <code>desiredCount</code> in sharding configuration (<a href="https://github.com/weaviate/weaviate/pull/11824" target="_blank" rel="noopener noreferrer" class="">#11824</a>)</li>
<li class=""><a href="https://github.com/Joe-Weaviate" target="_blank" rel="noopener noreferrer" class="">@Joe-Weaviate</a>: using <code>automaxprocs</code> to set <code>GOMAXPROCS</code>, adding cgroup v2 support (<a href="https://github.com/weaviate/weaviate/pull/11918" target="_blank" rel="noopener noreferrer" class="">#11918</a>)</li>
<li class=""><a href="https://github.com/VihaanAgarwal" target="_blank" rel="noopener noreferrer" class="">@VihaanAgarwal</a>: a fix to the object write path on collections with named vectors (<a href="https://github.com/weaviate/weaviate/pull/11919" target="_blank" rel="noopener noreferrer" class="">#11919</a>)</li>
<li class=""><a href="https://github.com/apoorva-01" target="_blank" rel="noopener noreferrer" class="">@apoorva-01</a>: returning <code>422</code> for a batch delete with missing match fields (<a href="https://github.com/weaviate/weaviate/pull/12049" target="_blank" rel="noopener noreferrer" class="">#12049</a>)</li>
</ul>
<p>If you'd like to contribute, check out the <a href="https://docs.weaviate.io/contributor-guide/" target="_blank" rel="noopener noreferrer" class="">contributor guide</a> and the <a href="https://github.com/weaviate/weaviate/issues" target="_blank" rel="noopener noreferrer" class=""><code>good-first-issue</code></a> label on GitHub.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="summary">Summary<a href="#summary" class="hash-link" aria-label="Direct link to Summary" title="Direct link to Summary" translate="no">​</a></h2>
<p>Weaviate <code>v1.39</code> promotes two search features to general availability, previews a third, and makes HNSW snapshots automatic.</p>
<p><strong>Key highlights:</strong></p>
<ul>
<li class=""><strong>Boost API (GA)</strong>: query-time rescoring that promotes or demotes results without dropping any, across hybrid, keyword, and vector searches</li>
<li class=""><strong>MMR Diversity Selection (GA)</strong>: diversity selection on hybrid and <code>near_*</code> searches, so page one covers the topic instead of repeating it</li>
<li class=""><strong>4-bit Rotational Quantization (Preview)</strong>: a third RQ width at 784 bytes per 1536-dimension vector, 7.84x smaller than raw <code>float32</code>, on HNSW indexes</li>
<li class=""><strong>Search REST API (Experimental)</strong>: JSON over plain HTTP/1.1, off by default. <code>near-text</code> in <code>v1.39.0</code>, plus <code>bm25</code>, <code>hybrid</code>, <code>near-object</code>, and an aggregate endpoint in <code>v1.39.1</code></li>
<li class=""><strong>gRPC-Web</strong>: the gRPC API reachable from a browser over ordinary HTTP, on the REST port, enabled by default since <code>v1.38.3</code></li>
<li class=""><strong>HNSW Snapshots, Automatic (GA)</strong>: less disk spent on commit logs, faster and steadier startup, five tuning knobs retired, and nothing left to schedule</li>
</ul>
<p><strong>Ready to get started?</strong></p>
<p>The release is available open-source on <a href="https://github.com/weaviate/weaviate/releases/tag/v1.39.0" target="_blank" rel="noopener noreferrer" class="">GitHub</a> and on <a href="https://console.weaviate.cloud/" target="_blank" rel="noopener noreferrer" class="">Weaviate Cloud</a>, where you can spin up a cluster on the free tier.</p>
<div class="theme-admonition theme-admonition-note admonition_xJq3 alert alert--secondary"><div class="admonitionHeading_Gvgb"><span class="admonitionIcon_Rf37"><svg viewBox="0 0 14 16"><path fill-rule="evenodd" d="M6.3 5.69a.942.942 0 0 1-.28-.7c0-.28.09-.52.28-.7.19-.18.42-.28.7-.28.28 0 .52.09.7.28.18.19.28.42.28.7 0 .28-.09.52-.28.7a1 1 0 0 1-.7.3c-.28 0-.52-.11-.7-.3zM8 7.99c-.02-.25-.11-.48-.31-.69-.2-.19-.42-.3-.69-.31H6c-.27.02-.48.13-.69.31-.2.2-.3.44-.31.69h1v3c.02.27.11.5.31.69.2.2.42.31.69.31h1c.27 0 .48-.11.69-.31.2-.19.3-.42.31-.69H8V7.98v.01zM7 2.3c-3.14 0-5.7 2.54-5.7 5.68 0 3.14 2.56 5.7 5.7 5.7s5.7-2.55 5.7-5.7c0-3.15-2.56-5.69-5.7-5.69v.01zM7 .98c3.86 0 7 3.14 7 7s-3.14 7-7 7-7-3.12-7-7 3.14-7 7-7z"></path></svg></span>note</div><div class="admonitionContent_BuS1"><p>Not all features may be available on Weaviate Cloud. Preview and experimental features, and anything that needs specific environment configuration, may not be enabled on managed clusters, or may arrive there on a different schedule.</p></div></div>
<p>If you are upgrading a self-hosted cluster, check the <a href="https://docs.weaviate.io/deploy/migration#general-upgrade-instructions" target="_blank" rel="noopener noreferrer" class="">migration guide</a> for version-specific notes.</p>
<p>Thanks for reading, and happy vector searching!</p>
<!-- -->
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="ready-to-start-building">Ready to start building?<a href="#ready-to-start-building" class="hash-link" aria-label="Direct link to Ready to start building?" title="Direct link to Ready to start building?" translate="no">​</a></h2>
<p>Check out the <a href="https://docs.weaviate.io/weaviate/quickstart" target="_blank" rel="noopener noreferrer" class="">Quickstart tutorial</a>, or <a href="https://console.weaviate.cloud/?utm_source=blog&amp;utm_medium=website&amp;utm_campaign=blog_signup&amp;utm_content=weaviate-1-39-release&amp;utm_term=ready-to-start-building" target="_blank" rel="noopener noreferrer">sign up for a free Weaviate Cloud account</a>.</p>
<!-- -->
]]></content:encoded>
            <category>release</category>
            <category>engineering</category>
        </item>
        <item>
            <title><![CDATA[Building Foundry Part 2: Where creative workflows break]]></title>
            <link>https://weaviate.io/blog/building-foundry-where-workflows-break</link>
            <guid>https://weaviate.io/blog/building-foundry-where-workflows-break</guid>
            <pubDate>Thu, 13 Aug 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[Part 2: Why folders, tags, and keyword search break down in real creative workflows and what retrieval needs to do instead.]]></description>
            <content:encoded><![CDATA[<p><img decoding="async" loading="lazy" alt="hero" src="/assets/images/hero-b49ceec72fc24ffc33651dad0b9254ab.jpg" width="1200" height="630" class="img_ev3q"></p>
<blockquote>
<p><strong>Building Foundry</strong><br>
<!-- -->A practical series on creative workflows, semantic search, and Weaviate.</p>
</blockquote>
<p>Read the previous post in the series: <a class="" href="/blog/building-foundry-ai-creative-workflows">Part 1: AI isn't replacing creativity, it's removing friction</a>.</p>
<p>Most creative teams already know they are losing time to search. What is less obvious is where the breakdown actually happens. It usually doesn’t begin with bad tools or careless teams. Instead, as projects scale, naming conventions drift, metadata quality drops, and the cost of keeping everything perfectly organized becomes higher than the cost of living with a little chaos. For a while, that tradeoff feels reasonable. Then retrieval starts to fail, and no one can find anything anymore.</p>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="the-first-failure-folders">The first failure: folders<a href="#the-first-failure-folders" class="hash-link" aria-label="Direct link to The first failure: folders" title="Direct link to The first failure: folders" translate="no">​</a></h2>
<p><img decoding="async" loading="lazy" alt="Creative workflows fail at retrieval" src="/assets/images/image-1-632a861d68500666556ee0ba3eca3fbf.jpg" width="1448" height="1086" class="img_ev3q"></p>
<p>Folder trees work best when projects are small, ownership is stable, and everyone agrees on the same mental model. Creative production rarely stays in that state for long.</p>
<p>In game development, one environment team might organize assets by biome, another by sprint, and another by engine-ready status. All three structures make sense locally. Across a two-year production, they become incompatible maps of the same work. In film production, footage often starts organized by shoot day, then gets reorganized by sequence in editorial, while VFX and color keep their own derivative structures. In design teams, client work, exploration files, and final exports often live in separate systems with weak links between them.</p>
<p>Folders still matter, but over time they describe where a file landed, not what that file is useful for.</p>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="the-second-failure-tags">The second failure: tags<a href="#the-second-failure-tags" class="hash-link" aria-label="Direct link to The second failure: tags" title="Direct link to The second failure: tags" translate="no">​</a></h2>
<p>Tagging is usually proposed as the cure for messy folders, and in controlled environments it can work well. The challenge is that consistent tagging is a process discipline, and process discipline is fragile under deadline pressure.</p>
<p>Animation teams shipping sequences on tight schedules do not stop to apply perfect descriptive tags to every versioned scene file. Music producers bouncing between sessions do not pause to classify each stem with reusable semantic labels. Designers preparing campaign variants for multiple channels rarely annotate every intermediate exploration with future retrieval in mind.</p>
<p>None of this reflects poor craft. It reflects incentives. Teams optimize for shipping what is needed now, not for a hypothetical retrieval request six months later. As a result, tag quality tends to be uneven: high for formal deliverables, sparse for working files, and inconsistent across individuals.</p>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="the-third-failure-keyword-search">The third failure: keyword search<a href="#the-third-failure-keyword-search" class="hash-link" aria-label="Direct link to The third failure: keyword search" title="Direct link to The third failure: keyword search" translate="no">​</a></h2>
<p><img decoding="async" loading="lazy" alt="Keyword vs Semantic" src="/assets/images/image-2-59e506ebefc4430cd43ddf9ee3ab186b.jpg" width="1448" height="1086" class="img_ev3q"></p>
<p>Keyword search is excellent when the query and the stored text use the same words. But creative work is full of vocabulary mismatch. A film editor might search for "quiet emotional close-up" while a clip is described internally as "CU actor B reaction alt take." A game artist may search "wet brutalist corridor" while files are named around level IDs and sprint numbers. A graphic designer searching for "playful geometric logo options" may be looking for a file titled <code>final_FINAL_logo_v7</code>, because the client came back half a dozen times with edits.</p>
<p>Creative work is messy, and file names rarely contain the descriptions we need to find them again.</p>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="these-failures-compound-over-time">These failures compound over time<a href="#these-failures-compound-over-time" class="hash-link" aria-label="Direct link to These failures compound over time" title="Direct link to These failures compound over time" translate="no">​</a></h2>
<p>Any one of these issues is manageable. Together, they create a compounding effect.</p>
<p>A project starts with a clean structure. Team members rotate. Vendors contribute assets using different conventions. Naming drift increases. Tagging discipline varies by deadline and role. Archive volume grows. Eventually the team has not one system but several partially overlapping systems. At that point, finding material becomes less about search and more about social memory: asking the person who might remember.</p>
<p>That approach does not scale. It also creates uneven access to institutional knowledge. Senior contributors become implicit search engines, and new team members spend longer rebuilding context that already exists in files they cannot easily discover.</p>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="what-retrieval-needs-to-do-differently">What retrieval needs to do differently<a href="#what-retrieval-needs-to-do-differently" class="hash-link" aria-label="Direct link to What retrieval needs to do differently" title="Direct link to What retrieval needs to do differently" translate="no">​</a></h2>
<p><img decoding="async" loading="lazy" alt="Workflow Diagram" src="/assets/images/image-3-16b4c12f8f28599732e09ea7c73d0c89.jpg" width="1448" height="1086" class="img_ev3q"></p>
<p>If we treat this as a retrieval problem rather than an organization problem, requirements change.</p>
<p>Retrieval has to work when naming is imperfect. It has to work when tags are incomplete. It has to work when the user can describe intent clearly but cannot reproduce the original wording used at creation time. It also has to preserve precision when exact constraints matter, such as project, date range, rights status, delivery format, or asset type.</p>
<p>That is why modern systems combine multiple signals:</p>
<ul>
<li class="">semantic similarity for meaning</li>
<li class="">keyword matching for exact terms</li>
<li class="">metadata filters for hard constraints</li>
</ul>
<p>This can be built using a two-phase path: ingestion first, retrieval second.</p>
<p>Ingestion is where assets are prepared for future search. Files are processed, embeddings are generated, and available metadata is attached. In creative pipelines, this can include project identifiers, file types, timestamps, contributor roles, rights or licensing fields, and any production-specific attributes you already track. The goal is to capture enough structure and enough semantic representation that future queries have multiple routes to the right result.</p>
<p>Retrieval is where those routes are combined. A user might search in natural language, then refine with metadata filters, then rely on hybrid ranking that blends semantic and keyword scores. Vector databases can store embeddings with metadata at scale, which means semantic and filtered search can run in one coherent flow.</p>
<p>Using Weaviate as an implementation example, we can ingest assets with embeddings and metadata, query with vector and keyword signals, then apply metadata constraints for production-safe results.</p>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="whats-next">What’s next<a href="#whats-next" class="hash-link" aria-label="Direct link to What’s next" title="Direct link to What’s next" translate="no">​</a></h2>
<p>Creative workflows do not break because teams are disorganized. They break because production systems are optimized for shipping, while media retrieval systems are often optimized for ideal data hygiene that real projects cannot maintain.</p>
<p>Building a vector-based retrieval system is the practical direction for teams that want less time lost to searching and less creative work stranded in archives.</p>
<p>In the next post, we’ll begin that implementation with the foundation: data ingestion. A read-only discovery pass will scan a messy creative archive and turn it into a structured manifest ready for metadata enrichment and vector embeddings. From there, we can ingest those records into Weaviate and add hybrid queries and metadata filtering.</p>
<hr>
<!-- -->
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="ready-to-start-building">Ready to start building?<a href="#ready-to-start-building" class="hash-link" aria-label="Direct link to Ready to start building?" title="Direct link to Ready to start building?" translate="no">​</a></h2>
<p>Check out the <a href="https://docs.weaviate.io/weaviate/quickstart" target="_blank" rel="noopener noreferrer" class="">Quickstart tutorial</a>, or <a href="https://console.weaviate.cloud/?utm_source=blog&amp;utm_medium=website&amp;utm_campaign=blog_signup&amp;utm_content=building-foundry-where-workflows-break&amp;utm_term=ready-to-start-building" target="_blank" rel="noopener noreferrer">sign up for a free Weaviate Cloud account</a>.</p>
<!-- -->
]]></content:encoded>
            <category>creative-ai</category>
            <category>workflows</category>
            <category>search</category>
        </item>
        <item>
            <title><![CDATA[Scaling Test-Time Compute in Search Mode]]></title>
            <link>https://weaviate.io/blog/search-mode-effort</link>
            <guid>https://weaviate.io/blog/search-mode-effort</guid>
            <pubDate>Tue, 11 Aug 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[Introducing medium, high, and ultrahigh effort tiers to the Query Agent's Search Mode.]]></description>
            <content:encoded><![CDATA[<p><img decoding="async" loading="lazy" alt="hero" src="/assets/images/hero-8237f87f091069c1c1123d1ef022c83a.png" width="1200" height="630" class="img_ev3q"></p>
<p>Scaling test-time compute has become one of the clearest successes of the foundation model era. Spend more compute on a problem at inference, get a better result. Retrieval is no exception. The new <code>effort</code> parameter in the Query Agent’s <a href="https://docs.weaviate.io/query-agent/guides/search_mode" target="_blank" rel="noopener noreferrer" class="">Search Mode</a> now lets you control this. On BRIGHT Biology, one of the hardest reasoning-intensive retrieval benchmarks, ultrahigh effort Search Mode lifts nDCG@10 to 57.5 compared to 13.0 with Hybrid Search alone.</p>
<p>Different applications sit at different points on the accuracy / latency tradeoff curve. Available in <code>weaviate-agents 1.8.0</code> and <code>agents-typescript-client 1.7.0</code>, <code>effort</code> lets you choose per request how much work the Query Agent invests in each search.</p>
<!-- -->
<div class="theme-tabs-container tabs-container tabList__CuJ"><ul role="tablist" aria-orientation="horizontal" class="tabs"><li role="tab" tabindex="0" aria-selected="true" class="tabs__item tabItem_LNqP tabs__item--active">Python</li><li role="tab" tabindex="-1" aria-selected="false" class="tabs__item tabItem_LNqP">JS/TS</li></ul><div class="margin-top--md"><div role="tabpanel" class="tabItem_Ymn6"><div class="language-python codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-python codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">from</span><span class="token plain"> weaviate</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">agents</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">query </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">import</span><span class="token plain"> QueryAgent</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">qa </span><span class="token operator">=</span><span class="token plain"> QueryAgent</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">  client</span><span class="token operator">=</span><span class="token plain">client</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">  collections</span><span class="token operator">=</span><span class="token punctuation" style="color:rgb(248, 248, 242)">[</span><span class="token string" style="color:rgb(255, 121, 198)">"IRPAPERS"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">]</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">response </span><span class="token operator">=</span><span class="token plain"> qa</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">search</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">  </span><span class="token string" style="color:rgb(255, 121, 198)">"What are Listwise Rerankers?"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">  effort</span><span class="token operator">=</span><span class="token string" style="color:rgb(255, 121, 198)">"ultrahigh"</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><br></span></code></pre></div></div></div><div role="tabpanel" class="tabItem_Ymn6" hidden=""><div class="language-typescript codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-typescript codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">import</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">{</span><span class="token plain"> QueryAgent </span><span class="token punctuation" style="color:rgb(248, 248, 242)">}</span><span class="token plain"> </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">from</span><span class="token plain"> </span><span class="token string" style="color:rgb(255, 121, 198)">"weaviate-agents"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">const</span><span class="token plain"> qa </span><span class="token operator">=</span><span class="token plain"> </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">new</span><span class="token plain"> </span><span class="token class-name">QueryAgent</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain">client</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">  collections</span><span class="token operator">:</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">[</span><span class="token string" style="color:rgb(255, 121, 198)">"IRPAPERS"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">]</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token punctuation" style="color:rgb(248, 248, 242)">}</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">const</span><span class="token plain"> response </span><span class="token operator">=</span><span class="token plain"> </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">await</span><span class="token plain"> qa</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token function" style="color:rgb(80, 250, 123)">search</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token string" style="color:rgb(255, 121, 198)">"What are Setwise Rerankers?"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">  effort</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:rgb(255, 121, 198)">"ultrahigh"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token punctuation" style="color:rgb(248, 248, 242)">}</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">;</span><br></span></code></pre></div></div></div></div></div>
<p>Search Mode’s three <code>effort</code> tiers: <code>medium</code>, <code>high</code>, and <code>ultrahigh</code> scale computation at the two stages where Search Mode does its work: query writing and reranking. At higher effort, the agent thinks longer about how to decompose queries and reranks results more thoroughly. At lower effort, it trades some of that depth for speed and cost. Turn it up when the answer matters, and turn it down when latency does!</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="benchmarks">Benchmarks<a href="#benchmarks" class="hash-link" aria-label="Direct link to Benchmarks" title="Direct link to Benchmarks" translate="no">​</a></h2>
<p>The following table compares our <code>medium</code>, <code>high</code>, and <code>ultrahigh</code> effort tiers in Search Mode against Weaviate’s Hybrid Search across 8 benchmarks: 5 subsets from <a href="https://arxiv.org/abs/2407.12883" target="_blank" rel="noopener noreferrer" class="">BRIGHT</a>, <a href="https://arxiv.org/abs/2602.17687" target="_blank" rel="noopener noreferrer" class="">IRPAPERS</a>, <a href="https://arxiv.org/abs/2505.08643" target="_blank" rel="noopener noreferrer" class="">WixQA</a>, and a subset from <a href="https://arxiv.org/pdf/2605.06235" target="_blank" rel="noopener noreferrer" class="">OBLIQ-Bench</a>. We chose these benchmarks because they illustrate reasoning-intensive and domain-specific retrieval problems.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="methodology">Methodology<a href="#methodology" class="hash-link" aria-label="Direct link to Methodology" title="Direct link to Methodology" translate="no">​</a></h3>
<p>As in our first Search Mode Benchmarking blog, we compare against Weaviate's Hybrid Search, combining BM25 with vector search over Snowflake Arctic 2.0 embeddings, fused with Reciprocal Rank Fusion (RRF). We then run Search Mode at each of the three effort tiers on the same collections. To account for the stochasticity of the models used in Search Mode, every Search Mode configuration is run for 3 trials, and we report the mean and standard deviation across trials. Hybrid Search is nearly deterministic given a fixed collection, so we report a single run.</p>
<h4 class="anchor anchorTargetStickyNavbar_Vzrq" id="metrics-glossary">Metrics Glossary<a href="#metrics-glossary" class="hash-link" aria-label="Direct link to Metrics Glossary" title="Direct link to Metrics Glossary" translate="no">​</a></h4>
<ul>
<li class=""><strong>Gold Document</strong>: In IR benchmarks, the "gold document" is the labeled relevant document, or documents, for a given query.</li>
<li class=""><strong>Success@K</strong>: Measures whether or not the K retrieved documents are gold documents. We typically report Success when setting K = 1 to account for multiple gold documents per query.</li>
<li class=""><strong>Recall@K</strong>: Measures how many of the gold documents are in the top K results.</li>
<li class=""><strong>nDCG@K</strong>: Short for normalized Discounted Cumulative Gain, nDCG considers not only whether relevant documents are retrieved, but also how they are ordered. Its strength lies in capturing graded relevance rather than binary relevance, and rewarding systems that place the best results higher in the list.</li>
</ul>
<hr>
<p>For all metrics, higher values indicate better performance. Each metric emphasizes a different aspect of information retrieval, and together they provide a fuller picture.</p>
<hr>
<h4 class="anchor anchorTargetStickyNavbar_Vzrq" id="benchmarks-glossary">Benchmarks Glossary<a href="#benchmarks-glossary" class="hash-link" aria-label="Direct link to Benchmarks Glossary" title="Direct link to Benchmarks Glossary" translate="no">​</a></h4>
<ul>
<li class=""><strong>BRIGHT</strong>: Featured in ICLR 2025, BRIGHT tests reasoning-intensive retrieval with long, descriptive queries sampled from StackExchange posts. The gold documents are web pages cited in accepted or highly upvoted answers. We use 5 subsets: Biology, Earth Science, Economics, Psychology, and Robotics.</li>
<li class=""><strong>IRPAPERS</strong>: Our benchmark of Information Retrieval papers, published at the start of 2026 to study domain-specific retrieval and compare text- and image-based systems. We report results on the text transcriptions.</li>
<li class=""><strong>WixQA</strong>: Released by the <a href="https://www.wix.com" target="_blank" rel="noopener noreferrer" class="">Wix.com</a> AI Research team in May 2025, WixQA tests domain-specific technical support retrieval with 200 expert-written customer queries, each paired with gold documents authored by Wix support specialists.</li>
<li class=""><strong>OBLIQ-Bench</strong>: Introduced by MIT researchers in May 2026, OBLIQ-Bench targets queries where relevance is latent, or oblique, rather than stated in the document's surface text. We use the Congress Hearings subset with 254 tip-of-the-tongue queries over 213,650 congressional hearing passages.</li>
</ul>
<p><img decoding="async" loading="lazy" alt="Search Mode Effort Benchmarks" src="/assets/images/metric-viewer-b427e4b333181a2554e0bfcb5ce5a7b8.png" width="2194" height="2060" class="img_ev3q"></p>
<p>Across all eight benchmarks, the pattern is consistent: every <code>effort</code> tier of Search Mode outperforms Hybrid Search, and higher effort delivers higher accuracy on average. The size of the gap between tiers depends on the problem. On BRIGHT, where queries demand multi-step reasoning, the tiers separate sharply. Ultrahigh effort lifts nDCG@10 from 13.0 to 57.5 on Biology and from 22.2 to 54.4 on Psychology, with each step up in effort buying meaningful additional accuracy. On domain-specific, but less reasoning-intensive benchmarks like IRPAPERS and WixQA, the gap shrinks. Here medium effort already captures most of the gain over Hybrid Search, and higher tiers add smaller increments on top.</p>
<p>Because Search Mode’s inference pipeline is stochastic, adjacent tiers can overlap on individual datasets. For example, on BRIGHT Economics, medium effort edges out high. Averaged across benchmarks and trials, the ordering holds and higher effort consistently delivers higher accuracy. Standard deviations are computed across three trials per system, and the consistency across runs gives us confidence these gains are robust rather than artifacts of a single sample.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="bright">BRIGHT<a href="#bright" class="hash-link" aria-label="Direct link to BRIGHT" title="Direct link to BRIGHT" translate="no">​</a></h3>
<p><img decoding="async" loading="lazy" alt="BRIGHT results" src="/assets/images/bright-average-of-5-subsets-ee93494c520639431983a3a201f82a54.png" width="2328" height="1192" class="img_ev3q"></p>
<p>The BRIGHT subsets reward effort differently. On Biology and Psychology, each step up in effort buys a meaningful gain, with ultrahigh effort roughly quadrupling Hybrid Search's nDCG@10 on Biology. Earth Science tells a different story, where medium effort already triples the Hybrid Search baseline and the higher tiers add smaller refinements on top. Robotics is the most striking case where medium and high effort improve on Hybrid Search only modestly, but ultrahigh effort jumps well past both, lifting Success@1 from 25.7 at medium to 45.9 at high. Robotics also has by far the longest queries of the five subsets, averaging 819 tokens, which suggests the hardest queries are exactly where the extra computation pays off most.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="irpapers">IRPAPERS<a href="#irpapers" class="hash-link" aria-label="Direct link to IRPAPERS" title="Direct link to IRPAPERS" translate="no">​</a></h3>
<p><img decoding="async" loading="lazy" alt="IRPAPERS results" src="/assets/images/irpapers-text-only-ddcb2e87c955f55c6faddbd971df89cb.png" width="1828" height="1192" class="img_ev3q"></p>
<p>Compared to BRIGHT, the effort tiers sit much closer together on IRPAPERS. Medium effort already captures most of the gain over Hybrid Search, with high and ultrahigh adding only a couple of points on top.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="wixqa">WixQA<a href="#wixqa" class="hash-link" aria-label="Direct link to WixQA" title="Direct link to WixQA" translate="no">​</a></h3>
<p><img decoding="async" loading="lazy" alt="WixQA results" src="/assets/images/wixqa-ec441205525a6e8528c111d9948be0d9.png" width="1828" height="1192" class="img_ev3q"></p>
<p>The pattern from IRPAPERS repeats here. Every Search Mode effort tier clears Hybrid Search by a wide margin, while the gaps between effort tiers stay small. In practical terms, even at medium effort, Search Mode returns the document a Wix support specialist would hand you at rank 1 for about two out of three customer questions, compared to two out of five with Hybrid Search. On benchmarks like these, where queries are shorter and demand less multi-step reasoning than BRIGHT, medium effort seems to capture most of the available gain. For latency-sensitive applications or to save cost, it may be worth testing whether the cheapest tier is already enough.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="obliq-bench">OBLIQ-Bench<a href="#obliq-bench" class="hash-link" aria-label="Direct link to OBLIQ-Bench" title="Direct link to OBLIQ-Bench" translate="no">​</a></h3>
<p><img decoding="async" loading="lazy" alt="OBLIQ-Bench results" src="/assets/images/obliq-bench-congress-ce7268482a696b5f8965952a50a00fa0.png" width="2328" height="1192" class="img_ev3q"></p>
<p>These are the lowest absolute scores in this analysis. Hybrid Search essentially hits the floor, surfacing the gold passage in its top 20 results for fewer than 1 in 12 queries. Search Mode changes the picture substantially. Ultrahigh effort reaches 24.4 Success@1, roughly a 7x improvement over Hybrid Search, and this is the one benchmark where the tiers stay cleanly separated on every metric. Each step up in effort buys a real gain, reinforcing the pattern from BRIGHT that the hardest problems reward the most computation.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="what-is-search-mode">What is Search Mode?<a href="#what-is-search-mode" class="hash-link" aria-label="Direct link to What is Search Mode?" title="Direct link to What is Search Mode?" translate="no">​</a></h2>
<p>The Query Agent is Weaviate’s agentic interface to your data. Instead of writing search queries, filters, and aggregations by hand, you describe what you want in natural language and the Query Agent figures out how to get it from your Weaviate collections. It comes in three modes: <strong>Ask Mode</strong>, which answers questions with generated responses grounded in your data, <strong>Search Mode</strong>, which returns the documents themselves, and <strong>Suggest Queries Mode</strong>, which proposes queries to help users explore what their collections can answer.</p>
<p>Search Mode is a drop-in upgrade for any pipeline that expects ranked search results and can tolerate additional latency, whether that’s a RAG system, an agentic workflow, or even a search bar.</p>
<p>The benchmarks so far have tested how well Search Mode finds relevant documents, but it can do more. Because the Query Agent understands your collection schemas, it can translate natural language into structured queries. For example, given a query such as, <em>"Find me some vintage shoes under $70"</em>, Search Mode recognizes "under $70" as a structured filter. It applies a hard constraint on the price property, and searches for vintage shoes among the results that qualify. This lets you combine semantic meaning and structured constraints with one system.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="conclusion">Conclusion<a href="#conclusion" class="hash-link" aria-label="Direct link to Conclusion" title="Direct link to Conclusion" translate="no">​</a></h2>
<p>Our benchmarks show what higher effort in Search Mode buys: consistent accuracy gains that grow with the difficulty of the retrieval problem. Additional effort trades latency and cost for that quality. If your application depends on surfacing the right result, such as agentic workflows, deep research, or high-stakes question answering, we recommend experimenting with the new effort tiers. If you are latency-sensitive, medium effort Search Mode or Weaviate's Hybrid Search remains a great fit.</p>
<p>All results can be found or reproduced with our open-source <a href="https://github.com/weaviate/query-agent-benchmarking" target="_blank" rel="noopener noreferrer" class="">query-agent-benchmarking</a> tool. This tool supports 22 benchmarks in total, further including benchmarks such as BEIR, LoTTe, EnronQA, and FreshStack if you would like to extend these comparisons. The tool further supports running the effort sweep comparison on your own search evals stored in Weaviate.</p>
<p>Thank you for reading!</p>
<!-- -->
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="ready-to-start-building">Ready to start building?<a href="#ready-to-start-building" class="hash-link" aria-label="Direct link to Ready to start building?" title="Direct link to Ready to start building?" translate="no">​</a></h2>
<p>Check out the <a href="https://docs.weaviate.io/weaviate/quickstart" target="_blank" rel="noopener noreferrer" class="">Quickstart tutorial</a>, or <a href="https://console.weaviate.cloud/?utm_source=blog&amp;utm_medium=website&amp;utm_campaign=blog_signup&amp;utm_content=search-mode-effort&amp;utm_term=ready-to-start-building" target="_blank" rel="noopener noreferrer">sign up for a free Weaviate Cloud account</a>.</p>
<!-- -->
]]></content:encoded>
            <category>agents</category>
            <category>search</category>
            <category>release</category>
        </item>
        <item>
            <title><![CDATA[Building Foundry: AI isn’t replacing creativity, it’s removing friction]]></title>
            <link>https://weaviate.io/blog/building-foundry-ai-creative-workflows</link>
            <guid>https://weaviate.io/blog/building-foundry-ai-creative-workflows</guid>
            <pubDate>Thu, 30 Jul 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[Why AI won’t replace creatives, and how it can remove friction from messy workflows, lost files, and creative processes.]]></description>
            <content:encoded><![CDATA[<p><img decoding="async" loading="lazy" alt="hero" src="/assets/images/hero-48d592d241a916c77429c6699c2c6ec3.jpg" width="1200" height="630" class="img_ev3q"></p>
<p>File names like <em>final_final_v7.png</em>, <em>USE_THIS_ONE.mov</em> or <em>new_character_export.psd</em> are oddly universal. They appear in game studios, post-production houses, animation pipelines, and design agencies working across every kind of project. The specific conventions vary, but the underlying situation does not: creative work accumulates faster than anyone can organise it, and finding something you made six months ago is often harder than making it again from scratch.</p>
<p>You don’t need better naming conventions or a different design tool to solve this. It’s a retrieval problem, and it’s one that most creative tools have never been designed to solve.</p>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="the-problem-isnt-creativity">The problem isn’t creativity<a href="#the-problem-isnt-creativity" class="hash-link" aria-label="Direct link to The problem isn’t creativity" title="Direct link to The problem isn’t creativity" translate="no">​</a></h2>
<p><img decoding="async" loading="lazy" alt="Creative workflows often break when trying to find and reuse work." src="/assets/images/messy-files-2c6ad19fe94bf807efe82d38b16989f6.jpg" width="1024" height="768" class="img_ev3q"></p>
<p>The persistent question in conversations about AI and creative work is whether AI can generate something: a painting, a screenplay, or a piece of music. But the more immediate and practical story is far less dramatic.</p>
<p>Consider how a game production pipeline actually works. A concept artist produces dozens of character sketches before one direction gets approved. The rejected explorations go into a folder named something like “alt_directions_v2”, and within three months nobody can reliably locate the version that sparked the final design. Then, on a sequel or expansion, someone needs that exact colour palette and aesthetic direction. Because searching for “dark armour character concepts 2023” turns up nothing useful, they start from scratch rather than building on what already exists.</p>
<p>The same problem looks different depending on the discipline. A film editor searching for specific B-roll scrolls through bins labelled by card number and shoot date, because nobody had time to write shot descriptions during production. An animator looking for a reference of a particular run cycle digs through folders three levels deep before giving up. A graphic designer trying to find an earlier logo exploration for a returning client reconstructs it from memory. A music producer hunting for a drum texture they used two years ago opens session after session, listening through stems, until they find it or settle for something new.</p>
<p>Searching for previous work, redesigning things that have already been done, and trying to stay organized in a sea of ever-growing media all take away from the creative work that actually matters.</p>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="where-time-actually-goes">Where time actually goes<a href="#where-time-actually-goes" class="hash-link" aria-label="Direct link to Where time actually goes" title="Direct link to Where time actually goes" translate="no">​</a></h2>
<p><img decoding="async" loading="lazy" alt="A surprising amount of creative time is spent searching." src="/assets/images/cake-58ca7e3da01a6b1ab803b81a5a4dae3b.jpg" width="1024" height="768" class="img_ev3q"></p>
<p>In most creative workflows, the actual moment of making something occupies a surprisingly small fraction of total project time. Pre-production and post-production dwarf the production itself. Research, reference gathering, asset organisation, version tracking, and the constant process of locating what already exists all compete for hours that would otherwise go toward the work.</p>
<p>Consider a scenario common in animation production: a rigging team needs to check how a particular character’s shoulder topology was handled in a previous project. There is no organised asset library, just a shared drive arranged by project name and date. The rig file is in there somewhere, but finding it requires either knowing exactly where to look or asking someone who does. If the person who built the original rig has since moved to a different studio, that knowledge leaves with them.</p>
<p>This is partly a documentation problem, but the right naming and organization only gets a team so far. The work exists. The information exists. But the inability to retrieve it efficiently is costing the team time, consistency, and sometimes money when they unknowingly reproduce work that already exists.</p>
<p>Traditional search compounds the problem rather than solving it. Keyword search requires you to guess which words were used when something was named or described, often by someone else, often months or years earlier. Searching for “blue environmental concept” returns nothing if the file is called <code>ENV_ALTSTYLING_DARK_V4</code>.</p>
<p>Weaviate is designed to handle this type of retrieval, storing semantic representations alongside traditional metadata so creative assets can be searched by both meaning and structured filters.</p>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="ai-as-a-workflow-layer">AI as a workflow layer<a href="#ai-as-a-workflow-layer" class="hash-link" aria-label="Direct link to AI as a workflow layer" title="Direct link to AI as a workflow layer" translate="no">​</a></h2>
<p>The most useful aspect of AI for creative fields isn’t as a generator of new work, but as the infrastructure layer that makes existing work more accessible.</p>
<p>This is where a class of technology called <a class="" href="/blog/vector-search-explained">semantic search</a> becomes genuinely relevant to creative workflows. To build this infrastructure layer, we can use semantic search to organize and retrieve documents based on meaning, not just by matching exact terms or phrases.</p>
<p>This works by using machine learning to change the original media into vector embeddings. A machine learning model processes a piece of content, whether that content is text, an image, or an audio file, and converts it into a long list of numbers that represents what the content means or depicts. Two things that mean a similar thing, even if described very differently, produce number sequences that sit close together in the resulting high-dimensional vector space. For example, a query for “dark forest with blue atmospheric haze” and an image of a misty pine forest at dusk will produce embeddings that cluster near each other in this space, even though neither the query nor the image share any matching text.</p>
<p>Vector search is the process of finding items whose embeddings are closest to a given query. That proximity is what enables retrieval by meaning rather than by keyword.</p>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="a-simple-example">A simple example<a href="#a-simple-example" class="hash-link" aria-label="Direct link to A simple example" title="Direct link to A simple example" translate="no">​</a></h2>
<p><img decoding="async" loading="lazy" alt="Weaviate Playground: comparing keyword, vector, and hybrid search. Showing how semantic search retrieves results based on meaning rather than exact words." src="/assets/images/search-0f0f08e6a27e2eb23984029c65dad3b3.jpg" width="1510" height="672" class="img_ev3q"></p>
<p>A game studio building an open-world RPG might accumulate tens of thousands of concept images over a multi-year production. Team composition changes, folder structures evolve, and naming conventions that were carefully maintained in year one have become considerably more creative by year three.</p>
<p>A designer joining the team near launch needs reference for a cold, forested biome that should feel visually distinct from the game’s existing environments. Searching for “cold forest biome” returns nothing useful from a keyword search because those files were named when nobody anticipated that particular query. A semantic search system, given the same natural-language description, can match against visual embeddings of the images themselves, automatically generated descriptions created during indexing, or a combination of both.</p>
<p>Before search becomes possible, content needs to be processed and stored in a way that supports semantic retrieval. This is the ingestion step: running files through a pipeline that generates an embedding for each item and stores that embedding alongside the original content and its metadata.</p>
<p>Metadata remains important even in a semantic search system. We still need to keep that information to know that our result belongs to the correct project, was created within the past two years, and is the right file type. So, in addition to our original media and our generated vector embeddings, it’s important that we store the file’s metadata as well.</p>
<p>A vector database holds all of this together. Unlike a traditional relational database designed for exact lookups, a vector database stores embeddings alongside the original data and metadata, with its internal architecture optimised for fast semantic retrieval. When you run a query, the database converts it into an embedding and returns the items whose embeddings are most similar. The result is search that appears to understand what you are actually looking for, not just what you typed. You can try the <a href="https://playground.weaviate.io/" target="_blank" rel="noopener noreferrer" class="">semantic search playground</a> to see the difference between keyword, vector, and hybrid results on the same query.</p>
<br>
<!-- -->
<br>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="this-is-just-the-start">This is just the start<a href="#this-is-just-the-start" class="hash-link" aria-label="Direct link to This is just the start" title="Direct link to This is just the start" translate="no">​</a></h2>
<p>None of what has been described here is beyond current technology. Semantic search and vector databases are already used in enterprise knowledge management, legal document retrieval, and e-commerce product search for exactly these reasons. We can apply those same principles to creative asset management.</p>
<p>The challenge lies in the ingestion layer: deciding what gets indexed, how descriptions and embeddings are generated for different content types, and how the search interface fits into existing tools and workflows.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="whats-next">What’s next<a href="#whats-next" class="hash-link" aria-label="Direct link to What’s next" title="Direct link to What’s next" translate="no">​</a></h2>
<p>In the next post, we’ll look closely at where creative workflows actually break down, and why conventional folder structures, tagging systems, and keyword search consistently fail to keep pace with how creative teams produce work. After that, we’ll walk through a concrete implementation: a working semantic search system for creative assets built with Weaviate, step by step.</p>
<hr>
<!-- -->
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="ready-to-start-building">Ready to start building?<a href="#ready-to-start-building" class="hash-link" aria-label="Direct link to Ready to start building?" title="Direct link to Ready to start building?" translate="no">​</a></h2>
<p>Check out the <a href="https://docs.weaviate.io/weaviate/quickstart" target="_blank" rel="noopener noreferrer" class="">Quickstart tutorial</a>, or <a href="https://console.weaviate.cloud/?utm_source=blog&amp;utm_medium=website&amp;utm_campaign=blog_signup&amp;utm_content=building-foundry-ai-creative-workflows&amp;utm_term=ready-to-start-building" target="_blank" rel="noopener noreferrer">sign up for a free Weaviate Cloud account</a>.</p>
<!-- -->
]]></content:encoded>
            <category>creative-ai</category>
            <category>workflows</category>
            <category>search</category>
        </item>
        <item>
            <title><![CDATA[Query Profiling: See Where a Slow Query Spends Its Time]]></title>
            <link>https://weaviate.io/blog/query-profiling</link>
            <guid>https://weaviate.io/blog/query-profiling</guid>
            <pubDate>Tue, 21 Jul 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[When a Weaviate query is slow, the first question is where the time went. Query profiling returns a per-stage, per-shard timing breakdown, making query performance issues visible.]]></description>
            <content:encoded><![CDATA[<p><img decoding="async" loading="lazy" alt="Where did the time go? Query profiling breaks a slow search into its stages." src="/assets/images/hero-d6ff5108f8f80410c4281a8d2c334533.png" width="1200" height="630" class="img_ev3q"></p>
<br>
<p>A query in production is slow. Maybe it was always a little slow and it finally crossed the line where someone noticed, or maybe it regressed after a data load. Either way you now have a single question, and it is the same question every time: where did the time go? Was it the filter, the vector search, the object read from disk, or the keyword scoring? Until you can split that number into its parts, every fix is a guess.</p>
<p>Weaviate has always been able to answer this. The trouble was getting the answer out.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="how-we-used-to-find-slow-queries">How we used to find slow queries<a href="#how-we-used-to-find-slow-queries" class="hash-link" aria-label="Direct link to How we used to find slow queries" title="Direct link to How we used to find slow queries" translate="no">​</a></h2>
<p>The existing tool is the <a href="https://docs.weaviate.io/deploy/configuration/logging#slow-query-logging" target="_blank" rel="noopener noreferrer" class="">slow query log</a>. You turn it on with two environment variables and restart the node:</p>
<div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token plain">QUERY_SLOW_LOG_ENABLED=true</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">QUERY_SLOW_LOG_THRESHOLD=2s</span><br></span></code></pre></div></div>
<p>Any query that runs longer than the threshold is logged at WARN with its full timing breakdown attached: the class and shard, the filters, the limit, and every internal timer the engine recorded on the way through. If you have <a href="https://docs.weaviate.io/deploy/configuration/env-vars" target="_blank" rel="noopener noreferrer" class="">runtime overrides</a> already wired up, you can flip both settings live from the overrides file and skip the restart, because the server rereads them on its load interval.</p>
<p>For catching regressions across a whole fleet over time, this works well. It is a passive net that stays out of the way until something trips it.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="where-the-old-approach-falls-short">Where the old approach falls short<a href="#where-the-old-approach-falls-short" class="hash-link" aria-label="Direct link to Where the old approach falls short" title="Direct link to Where the old approach falls short" translate="no">​</a></h2>
<p>The slow query log is built for a different job than the one you have when a specific query is slow right now, and four things get in the way.</p>
<p>First, the plain enablement path needs a restart. Restarting a node to debug a latency problem changes the thing you are measuring. A fresh process starts with cold OS page caches, so the first queries after a restart read from disk where a warm node would have hit memory. You end up profiling the restart as much as the query.</p>
<p>Second, the settings you tune live are temporary knobs. If you raised the threshold or toggled the log through runtime overrides to catch a specific query, that change lives in the overrides file, not in the deployment manifests your cluster is actually built from. It is a state you have to remember to undo, and it drifts out of sync with how the deployment is defined.</p>
<p>Third, it is always after the fact. The log only reacts once a query has already crossed the threshold. You cannot point it at the query in front of you and ask for its numbers; you wait for that query, or one like it, to be slow again. On top of that the log samples about one percent of all queries at INFO regardless of speed, so a fast query can show up in the output next to the genuinely slow ones and you have to filter the noise out.</p>
<p>Fourth, it is per node. Each node logs the shard searches that ran on it, and nothing stitches those lines together. On a single query that fans out across a cluster, the timings you want are spread across several nodes' logs, and reassembling one query's picture is manual work.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="what-is-query-profiling">What is query profiling?<a href="#what-is-query-profiling" class="hash-link" aria-label="Direct link to What is query profiling?" title="Direct link to What is query profiling?" translate="no">​</a></h2>
<p>Query profiling is the direct answer to all four. It is a per-query, opt-in flag. You set it on one search, the server collects the timing breakdown for that search, and it returns the numbers inline on the response. There is no env var, no threshold, no restart, and nothing to reset afterward.</p>
<p>Under the hood it uses the same instrumentation as the slow query log, so the numbers are the same numbers, delivered differently. And it closes the per-node gap directly: the coordinating node gathers the profiles from every shard on every node that took part in the query and returns them together. One request gives you the whole cluster's view of that one query.</p>
<p>You enable it per query. In Python, add it to the return metadata:</p>
<div class="language-python codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-python codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">from</span><span class="token plain"> weaviate</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">classes</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">query </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">import</span><span class="token plain"> MetadataQuery</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">response </span><span class="token operator">=</span><span class="token plain"> collection</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">query</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">near_vector</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    near_vector</span><span class="token operator">=</span><span class="token punctuation" style="color:rgb(248, 248, 242)">[</span><span class="token number">0.1</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> </span><span class="token number">0.2</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> </span><span class="token number">0.3</span><span class="token punctuation" style="color:rgb(248, 248, 242)">]</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    limit</span><span class="token operator">=</span><span class="token number">10</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    return_metadata</span><span class="token operator">=</span><span class="token plain">MetadataQuery</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain">query_profile</span><span class="token operator">=</span><span class="token boolean">True</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">for</span><span class="token plain"> shard </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">in</span><span class="token plain"> response</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">query_profile</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">shards</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">print</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain">shard</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">name</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> shard</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">node</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> shard</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">searches</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><br></span></code></pre></div></div>
<p>Query profiling is available in the official Python, JavaScript/TypeScript, Java (v6), and C# clients, and over gRPC directly by setting <code>QueryProfile</code> in the request metadata. The profile rides on the response object at <code>response.query_profile</code>, not on any individual result. Profiling covers vector search, keyword scoring, and filter evaluation. It does not measure generative modules, rerankers, or other post-processing.</p>
<p>Query profiling was <a href="https://docs.weaviate.io/weaviate/search/query-profile" target="_blank" rel="noopener noreferrer" class="">introduced in v1.36.9</a>, announced as a preview with the <a href="https://weaviate.io/blog/weaviate-1-37-release" target="_blank" rel="noopener noreferrer" class="">v1.37 release</a>, and is generally available as of v1.38. When the flag is off, the cost is a single boolean check. When it is on, the added cost is microsecond-level timer reads. It is meant for debugging and optimization, not for your production hot paths.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="reading-the-numbers">Reading the numbers<a href="#reading-the-numbers" class="hash-link" aria-label="Direct link to Reading the numbers" title="Direct link to Reading the numbers" translate="no">​</a></h2>
<p>The profile is organized by shard. Each shard entry names the shard and the node that ran it, and holds a <code>details</code> map of metric name to value for each search type it performed. A pure vector query shows the vector timers, a <a href="https://docs.weaviate.io/weaviate/search/bm25" target="_blank" rel="noopener noreferrer" class="">BM25</a> query shows the keyword timers, a <a href="https://docs.weaviate.io/weaviate/search/filters" target="_blank" rel="noopener noreferrer" class="">filtered</a> query adds the filter timers, and a hybrid query carries both a vector and a keyword section. Only the stages that actually ran show up, so the exact set of fields depends on the query.</p>
<p><img decoding="async" loading="lazy" alt="Search Metrics Diagram" src="/assets/images/search_metrics-81e866aca0bdfb9ae5ad303962df6607.png" width="2082" height="1515" class="img_ev3q"></p>
<p><code>total_took</code> is the wall time of the whole shard search. Everything else explains where that time went.</p>
<p>On the vector path, <code>objects_took</code> is object hydration: reading the final objects out of the on-disk objects store. A high value here means disk-bound hydration, and it usually points at page-cache misses, a large <code>limit</code>, or large objects. This is the clearest disk signal in the profile.</p>
<p><code>filters_build_allow_list_took</code> is filter resolution: turning your <code>where</code> clause into a set of matching document IDs through the <a href="https://docs.weaviate.io/weaviate/concepts/indexing" target="_blank" rel="noopener noreferrer" class="">inverted index</a>. It is driven by filter cardinality and by whether those index segments are in memory or on disk. The <code>filters_ids_matched</code> count sits right next to it and tells you which regime you are in. A large count means a broad filter matching many documents; a small count with a high time points more at disk reads.</p>
<p><code>vector_search_took</code> is the <a href="https://docs.weaviate.io/weaviate/concepts/vector-index" target="_blank" rel="noopener noreferrer" class="">vector index</a> doing its search, and its main sub-timer is <code>knn_search_layer_N_took</code>, one entry per HNSW layer, with layer 0 normally dominating. This is graph traversal: exploring candidates and computing distances. It is worth being precise here, because it is easy to read a high vector time as the node running out of resources. It usually is not. The HNSW graph lives in RAM, so this timer measures compute, not a wait on disk. A high value means the traversal itself is expensive, and the levers are the ones that control traversal cost: <code>ef</code>, vector dimensionality, and the filter strategy on filtered searches. Tune those before you reach for more hardware.</p>
<p>The one vector stage that can genuinely touch disk is <code>knn_search_rescore_took</code>. It only appears when compression is enabled, and it reads full-precision vectors back to rescore the compressed candidates. A high value there can mean disk latency during rescore, which is a different problem from a slow traversal.</p>
<p><code>hnsw_flat_search</code> is a boolean, not a timer. When it is <code>true</code> under a filter, the filter was selective enough that a brute-force scan of the matches was cheaper than walking the graph, and the engine took that path on purpose.</p>
<p>On the keyword path, the <code>kwd_*</code> family breaks BM25 down the same way. Two are worth knowing by name. <code>kwd_3_term_time</code> is the cost of reading the per-term posting lists out of the inverted segments, so it is sensitive to the number of query terms and to disk reads. <code>kwd_4_bmw_time</code> is the BlockMax WAND traversal that scores the posting blocks, so it grows with low query selectivity and long posting lists. A slow keyword query is usually one or the other, and the split tells you which.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="worked-examples">Worked examples<a href="#worked-examples" class="hash-link" aria-label="Direct link to Worked examples" title="Direct link to Worked examples" translate="no">​</a></h2>
<p>The numbers below are illustrative, but they show the shape of the output and how to read it.</p>
<p>A vector search where hydration dominates:</p>
<div class="language-json codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-json codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token punctuation" style="color:rgb(248, 248, 242)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">  </span><span class="token property">"shards"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">[</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    </span><span class="token punctuation" style="color:rgb(248, 248, 242)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">      </span><span class="token property">"name"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:rgb(255, 121, 198)">"1a2b3c4dshard"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">      </span><span class="token property">"node"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:rgb(255, 121, 198)">"weaviate-0"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">      </span><span class="token property">"searches"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">        </span><span class="token property">"vector"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">          </span><span class="token property">"details"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">            </span><span class="token property">"total_took"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:rgb(255, 121, 198)">"48.2ms"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">            </span><span class="token property">"filters_build_allow_list_took"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:rgb(255, 121, 198)">"2.1ms"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">            </span><span class="token property">"filters_ids_matched"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:rgb(255, 121, 198)">"512"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">            </span><span class="token property">"vector_search_took"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:rgb(255, 121, 198)">"8.4ms"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">            </span><span class="token property">"knn_search_layer_0_took"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:rgb(255, 121, 198)">"7.9ms"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">            </span><span class="token property">"knn_search_rescore_took"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:rgb(255, 121, 198)">"0.3ms"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">            </span><span class="token property">"hnsw_flat_search"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:rgb(255, 121, 198)">"false"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">            </span><span class="token property">"objects_took"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:rgb(255, 121, 198)">"36.8ms"</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">          </span><span class="token punctuation" style="color:rgb(248, 248, 242)">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">        </span><span class="token punctuation" style="color:rgb(248, 248, 242)">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">      </span><span class="token punctuation" style="color:rgb(248, 248, 242)">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    </span><span class="token punctuation" style="color:rgb(248, 248, 242)">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">  </span><span class="token punctuation" style="color:rgb(248, 248, 242)">]</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token punctuation" style="color:rgb(248, 248, 242)">}</span><br></span></code></pre></div></div>
<p>The filter and the vector search are cheap. <code>objects_took</code> is most of <code>total_took</code>, so the time is going into reading objects off disk. Check the page cache and storage on that node, and consider a smaller <code>limit</code> or a lighter payload.</p>
<p>A filter that matches too much:</p>
<div class="language-json codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-json codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token punctuation" style="color:rgb(248, 248, 242)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">  </span><span class="token property">"shards"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">[</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    </span><span class="token punctuation" style="color:rgb(248, 248, 242)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">      </span><span class="token property">"name"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:rgb(255, 121, 198)">"9f8e7d6cshard"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">      </span><span class="token property">"node"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:rgb(255, 121, 198)">"weaviate-1"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">      </span><span class="token property">"searches"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">        </span><span class="token property">"vector"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">          </span><span class="token property">"details"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">            </span><span class="token property">"total_took"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:rgb(255, 121, 198)">"61.5ms"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">            </span><span class="token property">"filters_build_allow_list_took"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:rgb(255, 121, 198)">"41.2ms"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">            </span><span class="token property">"filters_ids_matched"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:rgb(255, 121, 198)">"12840000"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">            </span><span class="token property">"vector_search_took"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:rgb(255, 121, 198)">"15.6ms"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">            </span><span class="token property">"knn_search_layer_0_took"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:rgb(255, 121, 198)">"14.8ms"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">            </span><span class="token property">"hnsw_flat_search"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:rgb(255, 121, 198)">"false"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">            </span><span class="token property">"objects_took"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:rgb(255, 121, 198)">"3.9ms"</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">          </span><span class="token punctuation" style="color:rgb(248, 248, 242)">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">        </span><span class="token punctuation" style="color:rgb(248, 248, 242)">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">      </span><span class="token punctuation" style="color:rgb(248, 248, 242)">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    </span><span class="token punctuation" style="color:rgb(248, 248, 242)">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">  </span><span class="token punctuation" style="color:rgb(248, 248, 242)">]</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token punctuation" style="color:rgb(248, 248, 242)">}</span><br></span></code></pre></div></div>
<p>Here <code>filters_build_allow_list_took</code> is the largest slice, and <code>filters_ids_matched</code> is over ten million. The filter is broad, so building the allow-list is the cost. This is a cardinality problem, not a disk one: rethink the filter so it selects less, or apply the wide condition differently rather than as a pre-filter over the whole set.</p>
<p>A compressed index where rescore hits disk:</p>
<div class="language-json codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-json codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token punctuation" style="color:rgb(248, 248, 242)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">  </span><span class="token property">"shards"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">[</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    </span><span class="token punctuation" style="color:rgb(248, 248, 242)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">      </span><span class="token property">"name"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:rgb(255, 121, 198)">"5c4b3a2fshard"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">      </span><span class="token property">"node"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:rgb(255, 121, 198)">"weaviate-0"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">      </span><span class="token property">"searches"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">        </span><span class="token property">"vector"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">          </span><span class="token property">"details"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">            </span><span class="token property">"total_took"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:rgb(255, 121, 198)">"39.7ms"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">            </span><span class="token property">"vector_search_took"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:rgb(255, 121, 198)">"35.1ms"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">            </span><span class="token property">"knn_search_layer_0_took"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:rgb(255, 121, 198)">"9.2ms"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">            </span><span class="token property">"knn_search_rescore_took"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:rgb(255, 121, 198)">"25.4ms"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">            </span><span class="token property">"hnsw_flat_search"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:rgb(255, 121, 198)">"false"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">            </span><span class="token property">"objects_took"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:rgb(255, 121, 198)">"3.8ms"</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">          </span><span class="token punctuation" style="color:rgb(248, 248, 242)">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">        </span><span class="token punctuation" style="color:rgb(248, 248, 242)">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">      </span><span class="token punctuation" style="color:rgb(248, 248, 242)">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    </span><span class="token punctuation" style="color:rgb(248, 248, 242)">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">  </span><span class="token punctuation" style="color:rgb(248, 248, 242)">]</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token punctuation" style="color:rgb(248, 248, 242)">}</span><br></span></code></pre></div></div>
<p>The graph traversal at layer 0 is fine. Almost all of <code>vector_search_took</code> is <code>knn_search_rescore_took</code>, the stage that reads full-precision vectors back for the compressed candidates. That points at disk latency during rescore rather than at the graph, so the investigation moves to storage and to the compression configuration.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="summary">Summary<a href="#summary" class="hash-link" aria-label="Direct link to Summary" title="Direct link to Summary" translate="no">​</a></h2>
<p>Query profiling has become one of the first things our solution engineering team reaches for when a customer reports a slow query. Instead of enabling a log, waiting for the query to be slow again, and stitching node logs together, you set one flag, run the query once, and read the breakdown across the whole cluster. The guesswork about where the time went is gone, and what is left is a specific stage to fix.</p>
<p>If you want help reading a profile or working out what to change based on one, reach out. Our solution engineering team looks at these breakdowns with customers on a regular basis, so if you are a customer, your usual Weaviate contact or support channel is the fastest way to get us the details. If you are running the open-source project, ask in the <a href="https://forum.weaviate.io/" target="_blank" rel="noopener noreferrer" class="">community forum</a> and we will help you work through it there.</p>
<p>To go deeper:</p>
<ul>
<li class=""><a href="https://docs.weaviate.io/weaviate/search/query-profile" target="_blank" rel="noopener noreferrer" class="">Query profiling</a> in the docs</li>
<li class=""><a href="https://docs.weaviate.io/deploy/configuration/logging#slow-query-logging" target="_blank" rel="noopener noreferrer" class="">Slow query logging</a></li>
<li class=""><a href="https://weaviate.io/blog/weaviate-1-37-release" target="_blank" rel="noopener noreferrer" class="">The Weaviate 1.37 release post</a></li>
</ul>
<!-- -->
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="ready-to-start-building">Ready to start building?<a href="#ready-to-start-building" class="hash-link" aria-label="Direct link to Ready to start building?" title="Direct link to Ready to start building?" translate="no">​</a></h2>
<p>Check out the <a href="https://docs.weaviate.io/weaviate/quickstart" target="_blank" rel="noopener noreferrer" class="">Quickstart tutorial</a>, or <a href="https://console.weaviate.cloud/?utm_source=blog&amp;utm_medium=website&amp;utm_campaign=blog_signup&amp;utm_content=query-profiling&amp;utm_term=ready-to-start-building" target="_blank" rel="noopener noreferrer">sign up for a free Weaviate Cloud account</a>.</p>
<!-- -->
]]></content:encoded>
            <category>concepts</category>
            <category>engineering</category>
            <category>search</category>
        </item>
        <item>
            <title><![CDATA[Weaviate 1.38 Release]]></title>
            <link>https://weaviate.io/blog/weaviate-1-38-release</link>
            <guid>https://weaviate.io/blog/weaviate-1-38-release</guid>
            <pubDate>Thu, 25 Jun 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[This release brings the HFresh disk-based vector index and the built-in MCP Server to general availability, rebuilds cluster-wide async replication to run from a single scheduler (on by default), and adds two previews: the Boost API and Nested Object Filtering.]]></description>
            <content:encoded><![CDATA[<p>Weaviate <code>v1.38</code> is now available open-source and on <a href="https://console.weaviate.cloud" target="_blank" rel="noopener noreferrer" class="">Weaviate Cloud</a>.</p>
<p>Two capabilities reach general availability in this release: the <strong>HFresh</strong> disk-based vector index and the built-in <strong>MCP Server</strong>. <strong>Async replication</strong> has been rebuilt to run cluster-wide from a single scheduler, and it now runs by default on every replicated collection. Two new previews join them: the <strong>Boost API</strong> for query-time rescoring and <strong>Nested Object Filtering</strong>.</p>
<p>Here are the release highlights!</p>
<p><img decoding="async" loading="lazy" alt="Weaviate 1.38 is released" src="/assets/images/hero-4a89efeaabb0804a755c5d50b90bcc88.png" width="1200" height="630" class="img_ev3q"></p>
<ul>
<li class=""><a href="#hfresh-vector-index---general-availability" class="">HFresh Vector Index - General Availability</a></li>
<li class=""><a href="#mcp-server---general-availability" class="">MCP Server - General Availability</a></li>
<li class=""><a href="#async-replication-everywhere" class="">Async Replication, Everywhere</a></li>
<li class=""><a href="#boost-api-preview" class="">Boost API (Preview)</a></li>
<li class=""><a href="#nested-object-filtering-preview" class="">Nested Object Filtering (Preview)</a></li>
<li class=""><a href="#performance-improvements-and-fixes" class="">Performance Improvements and Fixes</a></li>
<li class=""><a href="#community-contributions" class="">Community Contributions</a></li>
<li class=""><a href="#summary" class="">Summary</a></li>
</ul>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="hfresh-vector-index---general-availability">HFresh Vector Index - General Availability<a href="#hfresh-vector-index---general-availability" class="hash-link" aria-label="Direct link to HFresh Vector Index - General Availability" title="Direct link to HFresh Vector Index - General Availability" translate="no">​</a></h2>
<p><a class="" href="/blog/weaviate-1-36-release#hfresh-preview">HFresh</a>, the disk-based vector index we introduced as a technical preview in <code>v1.36</code>, is now <strong>generally available</strong>. It's inspired by the <a href="https://arxiv.org/abs/2410.14452" target="_blank" rel="noopener noreferrer" class="">SPFresh algorithm</a>: instead of keeping every vector in memory like HNSW, HFresh groups vectors into on-disk regions called <em>postings</em> and keeps a small in-memory HNSW index over their centroids to decide which regions to read. Memory stays low and latency stays predictable as a collection grows into the billions, which makes it a good fit for <strong>streaming workloads</strong> where data changes continuously rather than being loaded once.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="how-it-works">How it works<a href="#how-it-works" class="hash-link" aria-label="Direct link to How it works" title="Direct link to How it works" translate="no">​</a></h3>
<p>HFresh is selected per (named) vector, the same way as any other index. In <code>v1.38</code> it's no longer behind a preview flag — you enable it by configuring a vector to use it:</p>
<div class="language-python codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-python codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">from</span><span class="token plain"> weaviate</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">classes</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">config </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">import</span><span class="token plain"> Configure</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> VectorDistances</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">client</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">collections</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">create</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    </span><span class="token string" style="color:rgb(255, 121, 198)">"Article"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    vector_config</span><span class="token operator">=</span><span class="token plain">Configure</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">Vectors</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">text2vec_weaviate</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">        name</span><span class="token operator">=</span><span class="token string" style="color:rgb(255, 121, 198)">"default"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">        source_properties</span><span class="token operator">=</span><span class="token punctuation" style="color:rgb(248, 248, 242)">[</span><span class="token string" style="color:rgb(255, 121, 198)">"title"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> </span><span class="token string" style="color:rgb(255, 121, 198)">"body"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">]</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">        vector_index_config</span><span class="token operator">=</span><span class="token plain">Configure</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">VectorIndex</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">hfresh</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">            distance_metric</span><span class="token operator">=</span><span class="token plain">VectorDistances</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">COSINE</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">        </span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    </span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><br></span></code></pre></div></div>
<p>HFresh has <strong>RQ-1</strong> <a href="https://docs.weaviate.io/weaviate/concepts/vector-quantization" target="_blank" rel="noopener noreferrer" class="">quantization</a> built in: postings are stored compressed on disk, and final ranking rescores against the uncompressed vectors for accuracy. It supports the <code>cosine</code> and <code>l2-squared</code> distance metrics.</p>
<p>Because the index rebalances incrementally — splitting oversized postings, merging undersized ones, and reassigning vectors as the boundaries shift — it keeps up with continuous updates without the periodic full rebuilds that other on-disk indexes depend on.</p>
<div class="theme-admonition theme-admonition-info admonition_xJq3 alert alert--info"><div class="admonitionHeading_Gvgb"><span class="admonitionIcon_Rf37"><svg viewBox="0 0 14 16"><path fill-rule="evenodd" d="M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"></path></svg></span>Related resources</div><div class="admonitionContent_BuS1"><ul>
<li class=""><a href="https://docs.weaviate.io/weaviate/concepts/vector-index#hfresh-index" target="_blank" rel="noopener noreferrer" class="">Concepts: Vector Index - HFresh</a></li>
<li class=""><a href="https://arxiv.org/abs/2410.14452" target="_blank" rel="noopener noreferrer" class="">SPFresh: Incremental In-Place Update for Billion-Scale Vector Search</a></li>
</ul></div></div>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="mcp-server---general-availability">MCP Server - General Availability<a href="#mcp-server---general-availability" class="hash-link" aria-label="Direct link to MCP Server - General Availability" title="Direct link to MCP Server - General Availability" translate="no">​</a></h2>
<p>The built-in <a href="https://modelcontextprotocol.io/" target="_blank" rel="noopener noreferrer" class="">Model Context Protocol (MCP)</a> server, introduced as a preview in <a class="" href="/blog/weaviate-1-37-release#mcp-server-preview"><code>v1.37</code></a>, is now <strong>generally available</strong>. It lets LLMs, IDEs, and AI agents work with Weaviate directly — inspecting schemas, running hybrid searches, and writing objects back — with no glue code. The server is a Streamable HTTP endpoint at <code>/v1/mcp</code> on the same port as the REST API, authenticates with a Bearer / API-key token, and respects Weaviate's standard <a href="https://docs.weaviate.io/deploy/configuration/authorization" target="_blank" rel="noopener noreferrer" class="">RBAC</a> permissions.</p>
<p>The server exposes four tools:</p>
<ul>
<li class=""><strong><code>weaviate-collections-get-config</code></strong> — inspect a collection's schema and configuration</li>
<li class=""><strong><code>weaviate-tenants-list</code></strong> — list the tenants of a multi-tenant collection</li>
<li class=""><strong><code>weaviate-query-hybrid</code></strong> — run a hybrid (vector + keyword) search</li>
<li class=""><strong><code>weaviate-objects-upsert</code></strong> — insert or update objects (only when write access is enabled)</li>
</ul>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="how-it-works-1">How it works<a href="#how-it-works-1" class="hash-link" aria-label="Direct link to How it works" title="Direct link to How it works" translate="no">​</a></h3>
<p>You enable the server with <code>MCP_SERVER_ENABLED</code>, and optionally expose its write tools with <code>MCP_SERVER_WRITE_ACCESS_ENABLED</code>. What's new in <code>v1.38</code> is that both flags are <strong>runtime-configurable</strong>: rather than only being read at startup, Weaviate now picks up changes to them from its runtime-overrides file while the cluster is running.</p>
<div class="language-yaml codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-yaml codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token comment" style="color:rgb(98, 114, 164)"># Runtime-overrides file — applied without a restart</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token key atrule">mcp_server_enabled</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"> </span><span class="token boolean important">true</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token key atrule">mcp_server_write_access_enabled</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"> </span><span class="token boolean important">true</span><br></span></code></pre></div></div>
<p>So you can grant or revoke an agent's write access on a live cluster, with no rolling restart.</p>
<div class="theme-admonition theme-admonition-info admonition_xJq3 alert alert--info"><div class="admonitionHeading_Gvgb"><span class="admonitionIcon_Rf37"><svg viewBox="0 0 14 16"><path fill-rule="evenodd" d="M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"></path></svg></span>Related resources</div><div class="admonitionContent_BuS1"><ul>
<li class=""><a href="https://docs.weaviate.io/weaviate/configuration/mcp-server" target="_blank" rel="noopener noreferrer" class="">Docs: Weaviate MCP server</a></li>
<li class=""><a href="https://modelcontextprotocol.io/" target="_blank" rel="noopener noreferrer" class="">Model Context Protocol</a></li>
</ul></div></div>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="async-replication-everywhere">Async Replication, Everywhere<a href="#async-replication-everywhere" class="hash-link" aria-label="Direct link to Async Replication, Everywhere" title="Direct link to Async Replication, Everywhere" translate="no">​</a></h2>
<p>Async replication is the background repair process that keeps replicas in sync on collections with a replication factor greater than 1. In <code>v1.38</code> it has been re-architected to run <strong>cluster-wide from a single scheduler</strong>, rather than being configured and run separately per collection. It also now runs <strong>by default</strong> on every RF &gt; 1 collection, where previously it was opt-in per collection.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="how-it-works-2">How it works<a href="#how-it-works-2" class="hash-link" aria-label="Direct link to How it works" title="Direct link to How it works" translate="no">​</a></h3>
<p>One scheduler coordinates async repair across all replicated collections, drawing from a single shared worker pool instead of a separate pool per collection. That makes repair behavior consistent across the cluster and simpler to operate at scale.</p>
<p>With the move to a central scheduler, the per-collection <code>maxWorkers</code> and <code>enabled</code> settings are gone. Two cluster-level controls replace them:</p>
<div class="language-yaml codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-yaml codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token comment" style="color:rgb(98, 114, 164)"># Size of the shared async-replication worker pool</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token key atrule">ASYNC_REPLICATION_SCHEDULER_WORKERS</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"> </span><span class="token string" style="color:rgb(255, 121, 198)">'&lt;n&gt;'</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token comment" style="color:rgb(98, 114, 164)"># Kill-switch — pause all async replication, no restart needed</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token key atrule">ASYNC_REPLICATION_DISABLED</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"> </span><span class="token string" style="color:rgb(255, 121, 198)">'false'</span><br></span></code></pre></div></div>
<p><code>ASYNC_REPLICATION_SCHEDULER_WORKERS</code> sizes the shared pool, and <code>ASYNC_REPLICATION_DISABLED</code> is a cluster-wide kill-switch you can flip at runtime.</p>
<div class="theme-admonition theme-admonition-info admonition_xJq3 alert alert--info"><div class="admonitionHeading_Gvgb"><span class="admonitionIcon_Rf37"><svg viewBox="0 0 14 16"><path fill-rule="evenodd" d="M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"></path></svg></span>Related resources</div><div class="admonitionContent_BuS1"><ul>
<li class=""><a href="https://docs.weaviate.io/weaviate/concepts/replication-architecture" target="_blank" rel="noopener noreferrer" class="">Concepts: Replication architecture - Async replication</a></li>
<li class=""><a href="https://docs.weaviate.io/deploy/configuration/replication" target="_blank" rel="noopener noreferrer" class="">Configuration: Replication</a></li>
</ul></div></div>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="boost-api-preview">Boost API (Preview)<a href="#boost-api-preview" class="hash-link" aria-label="Direct link to Boost API (Preview)" title="Direct link to Boost API (Preview)" translate="no">​</a></h2>
<p>Sometimes you want to nudge results without removing any. A filter is too blunt for that — it drops everything that doesn't match — when what you really want is to rank fresh articles a little higher, or favor in-stock products, while keeping the full result set. The new <strong>Boost API</strong> does exactly that.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="how-it-works-3">How it works<a href="#how-it-works-3" class="hash-link" aria-label="Direct link to How it works" title="Direct link to How it works" translate="no">​</a></h3>
<p>Boost runs <em>after</em> the primary search. It re-scores the candidates by blending their original score with one or more boost conditions, then re-sorts them — promoting or demoting results without dropping any. Conditions can be based on:</p>
<ul>
<li class=""><strong>Filter matches</strong> — promote results that satisfy a filter</li>
<li class=""><strong>Property values</strong> — rank by a numeric property's value</li>
<li class=""><strong>Time decay</strong> — favor more recent (or near-a-date) objects</li>
<li class=""><strong>Numeric decay</strong> — favor objects closer to a target number</li>
</ul>
<p>In the Python client (<code>v4.22.0</code>+), you build a boost and pass it to any query via <code>boost=</code>:</p>
<div class="language-python codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-python codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">from</span><span class="token plain"> weaviate</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">classes</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">query </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">import</span><span class="token plain"> Boost</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> Filter</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token comment" style="color:rgb(98, 114, 164)"># Softly promote in-stock products without dropping the rest</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">response </span><span class="token operator">=</span><span class="token plain"> collection</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">query</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">hybrid</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    query</span><span class="token operator">=</span><span class="token string" style="color:rgb(255, 121, 198)">"wireless headphones"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    limit</span><span class="token operator">=</span><span class="token number">10</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    boost</span><span class="token operator">=</span><span class="token plain">Boost</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token builtin" style="color:rgb(189, 147, 249)">filter</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">        Filter</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">by_property</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token string" style="color:rgb(255, 121, 198)">"in_stock"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">equal</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token boolean">True</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">        weight</span><span class="token operator">=</span><span class="token number">0.3</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    </span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><br></span></code></pre></div></div>
<p>The <code>weight</code> (0–1) sets how much the boost shifts the final score: the result is <code>(1 - weight)</code> of the original score plus <code>weight</code> of the boost score. Boost is <strong>gRPC-only</strong> — there's no REST or GraphQL equivalent — and a single query can apply at most <strong>20 conditions</strong>.</p>
<div class="theme-admonition theme-admonition-caution admonition_xJq3 alert alert--warning"><div class="admonitionHeading_Gvgb"><span class="admonitionIcon_Rf37"><svg viewBox="0 0 16 16"><path fill-rule="evenodd" d="M8.893 1.5c-.183-.31-.52-.5-.887-.5s-.703.19-.886.5L.138 13.499a.98.98 0 0 0 0 1.001c.193.31.53.501.886.501h13.964c.367 0 .704-.19.877-.5a1.03 1.03 0 0 0 .01-1.002L8.893 1.5zm.133 11.497H6.987v-2.003h2.039v2.003zm0-3.004H6.987V5.987h2.039v4.006z"></path></svg></span>Preview</div><div class="admonitionContent_BuS1"><p>The Boost API is a <strong>preview</strong> feature, available over gRPC. The API and behavior may change in future releases.</p></div></div>
<div class="theme-admonition theme-admonition-info admonition_xJq3 alert alert--info"><div class="admonitionHeading_Gvgb"><span class="admonitionIcon_Rf37"><svg viewBox="0 0 14 16"><path fill-rule="evenodd" d="M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"></path></svg></span>Related resources</div><div class="admonitionContent_BuS1"><ul>
<li class=""><a href="https://docs.weaviate.io/weaviate/search/boost" target="_blank" rel="noopener noreferrer" class="">How-to: Search - Boost results</a></li>
</ul></div></div>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="nested-object-filtering-preview">Nested Object Filtering (Preview)<a href="#nested-object-filtering-preview" class="hash-link" aria-label="Direct link to Nested Object Filtering (Preview)" title="Direct link to Nested Object Filtering (Preview)" translate="no">​</a></h2>
<p>Weaviate <code>v1.38</code> adds a preview for <strong>filtering on nested object properties</strong>. Until now, <code>object</code> and <code>object[]</code> properties were stored but couldn't be filtered on directly.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="how-it-works-4">How it works<a href="#how-it-works-4" class="hash-link" aria-label="Direct link to How it works" title="Direct link to How it works" translate="no">​</a></h3>
<p>You filter on a nested field by referencing it with a <strong>dotted path</strong> — for example, <code>cars.make</code> to filter on the <code>make</code> field inside a <code>cars</code> object property. The feature is <strong>off by default</strong> and gated behind a preview environment variable:</p>
<div class="language-yaml codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-yaml codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token key atrule">WEAVIATE_PREVIEW_NESTED_FILTERING</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"> </span><span class="token string" style="color:rgb(255, 121, 198)">'true'</span><br></span></code></pre></div></div>
<p>Once enabled, the dotted path goes wherever you'd normally supply a property name, including from the clients:</p>
<div class="language-python codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-python codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">from</span><span class="token plain"> weaviate</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">classes</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">query </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">import</span><span class="token plain"> Filter</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">response </span><span class="token operator">=</span><span class="token plain"> collection</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">query</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">fetch_objects</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    filters</span><span class="token operator">=</span><span class="token plain">Filter</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">by_property</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token string" style="color:rgb(255, 121, 198)">"cars.make"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">equal</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token string" style="color:rgb(255, 121, 198)">"Toyota"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><br></span></code></pre></div></div>
<p>This works for data nested inside both <code>object</code> and <code>object[]</code> properties.</p>
<div class="theme-admonition theme-admonition-caution admonition_xJq3 alert alert--warning"><div class="admonitionHeading_Gvgb"><span class="admonitionIcon_Rf37"><svg viewBox="0 0 16 16"><path fill-rule="evenodd" d="M8.893 1.5c-.183-.31-.52-.5-.887-.5s-.703.19-.886.5L.138 13.499a.98.98 0 0 0 0 1.001c.193.31.53.501.886.501h13.964c.367 0 .704-.19.877-.5a1.03 1.03 0 0 0 .01-1.002L8.893 1.5zm.133 11.497H6.987v-2.003h2.039v2.003zm0-3.004H6.987V5.987h2.039v4.006z"></path></svg></span>Preview</div><div class="admonitionContent_BuS1"><p>Nested Object Filtering is a <strong>preview</strong> feature, off by default behind <code>WEAVIATE_PREVIEW_NESTED_FILTERING</code>. The API and behavior may change in future releases.</p></div></div>
<div class="theme-admonition theme-admonition-info admonition_xJq3 alert alert--info"><div class="admonitionHeading_Gvgb"><span class="admonitionIcon_Rf37"><svg viewBox="0 0 14 16"><path fill-rule="evenodd" d="M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"></path></svg></span>Related resources</div><div class="admonitionContent_BuS1"><ul>
<li class=""><a href="https://docs.weaviate.io/weaviate/search/filters" target="_blank" rel="noopener noreferrer" class="">How-to: Filters</a></li>
<li class=""><a href="https://docs.weaviate.io/weaviate/config-refs/datatypes" target="_blank" rel="noopener noreferrer" class="">Config references: Data types - object</a></li>
</ul></div></div>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="performance-improvements-and-fixes">Performance Improvements and Fixes<a href="#performance-improvements-and-fixes" class="hash-link" aria-label="Direct link to Performance Improvements and Fixes" title="Direct link to Performance Improvements and Fixes" translate="no">​</a></h2>
<p>Beyond the headline features, <code>v1.38</code> ships a long list of improvements. A few worth calling out:</p>
<ul>
<li class=""><strong>Production-ready replica movement:</strong> Moving a shard's replicas between nodes — for rebalancing and scaling — graduates to production-ready, backed by a change-capture log that keeps writes flowing during the move.</li>
<li class=""><strong>Default vector index type:</strong> A new cluster-level setting picks the default vector index for new collections (including named vectors), instead of always defaulting to HNSW.</li>
<li class=""><strong>Usage guardrails:</strong> Operators can set server-side limits on the number of objects, collections, tenants, and shards, plus allow-lists for vector-index and compression types.</li>
<li class=""><strong>New module — <code>text2vec-digitalocean</code>:</strong> Generate embeddings through DigitalOcean's inference platform.</li>
<li class=""><strong>Backup reliability:</strong> Backups no longer pause compactions, and object-storage listing is faster — both help large collections back up more reliably.</li>
<li class=""><strong>Fractional BM25 property boosts:</strong> Keyword-search property boosts now accept fractional values (e.g. <code>title^2.5</code>), not just integers.</li>
<li class=""><strong>Deterministic tie-breaking:</strong> Vector searches break ties between equal-distance results deterministically, for stable, repeatable ordering.</li>
<li class=""><strong>Faster startup</strong> and an improved cache for compressed vector indexes.</li>
</ul>
<div class="theme-admonition theme-admonition-info admonition_xJq3 alert alert--info"><div class="admonitionHeading_Gvgb"><span class="admonitionIcon_Rf37"><svg viewBox="0 0 14 16"><path fill-rule="evenodd" d="M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"></path></svg></span>Related resources</div><div class="admonitionContent_BuS1"><ul>
<li class=""><a href="https://github.com/weaviate/weaviate/releases/tag/v1.38.0" target="_blank" rel="noopener noreferrer" class="">Weaviate 1.38: GitHub Release Notes</a></li>
</ul></div></div>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="community-contributions">Community Contributions<a href="#community-contributions" class="hash-link" aria-label="Direct link to Community Contributions" title="Direct link to Community Contributions" translate="no">​</a></h2>
<p>Weaviate is open source, and this release includes work from several first-time contributors. Thank you to:</p>
<ul>
<li class=""><a href="https://github.com/dillonledoux" target="_blank" rel="noopener noreferrer" class="">@dillonledoux</a> — the new <code>text2vec-digitalocean</code> module (<a href="https://github.com/weaviate/weaviate/pull/11298" target="_blank" rel="noopener noreferrer" class="">#11298</a>)</li>
<li class=""><a href="https://github.com/anishesg" target="_blank" rel="noopener noreferrer" class="">@anishesg</a> — inverted-index and HFresh fixes, including correct handling of negative zero and pre-1970 dates (<a href="https://github.com/weaviate/weaviate/pull/11120" target="_blank" rel="noopener noreferrer" class="">#11120</a>)</li>
<li class=""><a href="https://github.com/msnandhis" target="_blank" rel="noopener noreferrer" class="">@msnandhis</a> — fractional BM25 property boosts (<a href="https://github.com/weaviate/weaviate/pull/11471" target="_blank" rel="noopener noreferrer" class="">#11471</a>)</li>
<li class=""><a href="https://github.com/3em0" target="_blank" rel="noopener noreferrer" class="">@3em0</a> — reject duplicate static API keys (<a href="https://github.com/weaviate/weaviate/pull/11393" target="_blank" rel="noopener noreferrer" class="">#11393</a>)</li>
<li class=""><a href="https://github.com/kedar49" target="_blank" rel="noopener noreferrer" class="">@kedar49</a> — collision check for DB user identifiers (<a href="https://github.com/weaviate/weaviate/pull/11381" target="_blank" rel="noopener noreferrer" class="">#11381</a>)</li>
<li class=""><a href="https://github.com/SAY-5" target="_blank" rel="noopener noreferrer" class="">@SAY-5</a> — HFresh stability fix during async init (<a href="https://github.com/weaviate/weaviate/pull/11087" target="_blank" rel="noopener noreferrer" class="">#11087</a>)</li>
</ul>
<p>If you'd like to contribute, check out the <a href="https://docs.weaviate.io/contributor-guide/" target="_blank" rel="noopener noreferrer" class="">contributor guide</a> and the <a href="https://github.com/weaviate/weaviate/issues" target="_blank" rel="noopener noreferrer" class=""><code>good-first-issue</code></a> label on GitHub.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="summary">Summary<a href="#summary" class="hash-link" aria-label="Direct link to Summary" title="Direct link to Summary" translate="no">​</a></h2>
<p>Weaviate <code>v1.38</code> brings two capabilities to general availability — HFresh and the MCP Server — alongside a rebuilt async replication path and two new previews.</p>
<p><strong>Key highlights:</strong></p>
<ul>
<li class=""><strong>HFresh (GA)</strong> — The disk-based, SPFresh-inspired vector index for streaming workloads, selected per named vector with <code>vectorIndexType: "hfresh"</code> and built-in RQ-1 quantization</li>
<li class=""><strong>MCP Server (GA)</strong> — The built-in Model Context Protocol server at <code>/v1/mcp</code>, with its enable flags now runtime-configurable</li>
<li class=""><strong>Async Replication, Everywhere</strong> — Cluster-wide async repair from one scheduler and a shared worker pool, on by default for replicated collections, with a runtime kill-switch</li>
<li class=""><strong>Boost API (Preview)</strong> — Query-time rescoring that promotes or demotes results without dropping any</li>
<li class=""><strong>Nested Object Filtering (Preview)</strong> — Filter on <code>object</code> / <code>object[]</code> properties using a dotted path</li>
</ul>
<p><strong>Ready to get started?</strong></p>
<p>The release is available open-source on <a href="https://github.com/weaviate/weaviate/releases/tag/v1.38.0" target="_blank" rel="noopener noreferrer" class="">GitHub</a> and on <a href="https://console.weaviate.cloud/" target="_blank" rel="noopener noreferrer" class="">Weaviate Cloud</a>, where you can spin up a cluster on the free tier.</p>
<div class="theme-admonition theme-admonition-note admonition_xJq3 alert alert--secondary"><div class="admonitionHeading_Gvgb"><span class="admonitionIcon_Rf37"><svg viewBox="0 0 14 16"><path fill-rule="evenodd" d="M6.3 5.69a.942.942 0 0 1-.28-.7c0-.28.09-.52.28-.7.19-.18.42-.28.7-.28.28 0 .52.09.7.28.18.19.28.42.28.7 0 .28-.09.52-.28.7a1 1 0 0 1-.7.3c-.28 0-.52-.11-.7-.3zM8 7.99c-.02-.25-.11-.48-.31-.69-.2-.19-.42-.3-.69-.31H6c-.27.02-.48.13-.69.31-.2.2-.3.44-.31.69h1v3c.02.27.11.5.31.69.2.2.42.31.69.31h1c.27 0 .48-.11.69-.31.2-.19.3-.42.31-.69H8V7.98v.01zM7 2.3c-3.14 0-5.7 2.54-5.7 5.68 0 3.14 2.56 5.7 5.7 5.7s5.7-2.55 5.7-5.7c0-3.15-2.56-5.69-5.7-5.69v.01zM7 .98c3.86 0 7 3.14 7 7s-3.14 7-7 7-7-3.12-7-7 3.14-7 7-7z"></path></svg></span>note</div><div class="admonitionContent_BuS1"><p>Not all features may be available on Weaviate Cloud. Some capabilities — preview features in particular, and those that require specific environment configuration — may not be enabled on managed clusters, or may become available on a different schedule.</p></div></div>
<p>For those upgrading a self-hosted version, please check the <a href="https://docs.weaviate.io/deploy/migration#general-upgrade-instructions" target="_blank" rel="noopener noreferrer" class="">migration guide</a> for version-specific notes.</p>
<p>Thanks for reading, and happy vector searching!</p>
<!-- -->
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="ready-to-start-building">Ready to start building?<a href="#ready-to-start-building" class="hash-link" aria-label="Direct link to Ready to start building?" title="Direct link to Ready to start building?" translate="no">​</a></h2>
<p>Check out the <a href="https://docs.weaviate.io/weaviate/quickstart" target="_blank" rel="noopener noreferrer" class="">Quickstart tutorial</a>, or <a href="https://console.weaviate.cloud/?utm_source=blog&amp;utm_medium=website&amp;utm_campaign=blog_signup&amp;utm_content=weaviate-1-38-release&amp;utm_term=ready-to-start-building" target="_blank" rel="noopener noreferrer">sign up for a free Weaviate Cloud account</a>.</p>
<!-- -->
]]></content:encoded>
            <category>release</category>
            <category>engineering</category>
        </item>
        <item>
            <title><![CDATA[Import & Vectorize Data with Weaviate at Scale]]></title>
            <link>https://weaviate.io/blog/data-import-best-practices</link>
            <guid>https://weaviate.io/blog/data-import-best-practices</guid>
            <pubDate>Thu, 18 Jun 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[Server-side batching, retries, the blobHash data type, and multimodal ingestion — what to use when, with code.]]></description>
            <content:encoded><![CDATA[<p><img decoding="async" loading="lazy" alt="Import and vectorize data with Weaviate at scale: server-side batching, retries, the blobHash data type, and multimodal ingestion" src="/assets/images/hero-3d3404ba029aa5e8104892b0590e738c.png" width="1200" height="630" class="img_ev3q"></p>
<p>Most vector database pilots fail at ingest, not at search. You build a clever retrieval pipeline, you watch it work on a thousand documents, and then someone hands you fifty million rows. The next two weeks disappear into rate limits, partial failures, and three rewrites of your batch logic.</p>
<p>This post is the guide I wish I had the first time I imported a real dataset into Weaviate. It covers server-side batching, error handling, the data type decisions that cost you the most if you get them wrong, and how to ingest media and PDFs without standing up an OCR pipeline.</p>
<div class="theme-admonition theme-admonition-info admonition_xJq3 alert alert--info"><div class="admonitionHeading_Gvgb"><span class="admonitionIcon_Rf37"><svg viewBox="0 0 14 16"><path fill-rule="evenodd" d="M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"></path></svg></span>Try this as you read</div><div class="admonitionContent_BuS1"><p>The fastest way to follow along is a <a href="https://console.weaviate.cloud/" target="_blank" rel="noopener noreferrer" class="">free Weaviate Cloud trial</a> paired with <a href="https://docs.weaviate.io/weaviate/model-providers" target="_blank" rel="noopener noreferrer" class="">Weaviate Embeddings</a>. No infrastructure to manage, no embedding API keys, free vectorization on the trial. Every code snippet below runs against that setup without modification.</p></div></div>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="the-ingest-problem-nobody-warns-you-about">The ingest problem nobody warns you about<a href="#the-ingest-problem-nobody-warns-you-about" class="hash-link" aria-label="Direct link to The ingest problem nobody warns you about" title="Direct link to The ingest problem nobody warns you about" translate="no">​</a></h2>
<p>A working prototype tells you nothing about what happens at scale. The problems that bite production teams almost never show up in tutorials.</p>
<p>Four bite hardest:</p>
<ul>
<li class=""><strong>Rate limits from your embedding provider:</strong> Most teams hit them within an hour of a real import, then write retry code, then write retry code for the retry code.</li>
<li class=""><strong>HTTP 200 lying to you:</strong> A successful batch response does not mean every object made it in. Individual objects can fail silently behind a green status code.</li>
<li class=""><strong>Duplicate work on retry:</strong> If you generate fresh IDs each time you re-run, you re-vectorize the same documents and pay for it twice.</li>
<li class=""><strong>Memory blowups on media:</strong> Loading a million product photos into a Python list ends your script before your batch logic ever runs.</li>
</ul>
<p>The rest of this post is what to do about each of them.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="server-side-batching">Server-side batching<a href="#server-side-batching" class="hash-link" aria-label="Direct link to Server-side batching" title="Direct link to Server-side batching" translate="no">​</a></h2>
<p>Server-side batching is a streaming import mode where the Weaviate server tells the client how much data to send next based on its own current workload. Instead of you guessing a batch size and a concurrency level, the server measures its queue depth and applies backpressure across a persistent connection.</p>
<p>This matters because the right batch size is not a constant. It depends on how many properties you have, the size of your text fields, whether you are vectorizing on the fly, what the vectorizer is doing under the hood, and what else the cluster is busy with. Hand-tuning it is brittle. The server has all of that information already.</p>
<p>Here is the pattern in the Python client:</p>
<div class="language-python codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-python codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">import</span><span class="token plain"> weaviate</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">from</span><span class="token plain"> weaviate</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">classes</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">init </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">import</span><span class="token plain"> Auth</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">client </span><span class="token operator">=</span><span class="token plain"> weaviate</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">connect_to_weaviate_cloud</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    cluster_url</span><span class="token operator">=</span><span class="token plain">WCD_URL</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    auth_credentials</span><span class="token operator">=</span><span class="token plain">Auth</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">api_key</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain">WCD_API_KEY</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">collection </span><span class="token operator">=</span><span class="token plain"> client</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">collections</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">get</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token string" style="color:rgb(255, 121, 198)">"Products"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">with</span><span class="token plain"> collection</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">batch</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">stream</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token plain"> </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">as</span><span class="token plain"> batch</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">for</span><span class="token plain"> row </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">in</span><span class="token plain"> iter_rows</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">        batch</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">add_object</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain">properties</span><span class="token operator">=</span><span class="token plain">row</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">        </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">if</span><span class="token plain"> batch</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">number_errors </span><span class="token operator">&gt;</span><span class="token plain"> </span><span class="token number">10</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">            </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">print</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token string" style="color:rgb(255, 121, 198)">"Too many errors, stopping."</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">            </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">break</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">if</span><span class="token plain"> collection</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">batch</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">failed_objects</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">print</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token string-interpolation string" style="color:rgb(255, 121, 198)">f"</span><span class="token string-interpolation interpolation punctuation" style="color:rgb(248, 248, 242)">{</span><span class="token string-interpolation interpolation builtin" style="color:rgb(189, 147, 249)">len</span><span class="token string-interpolation interpolation punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token string-interpolation interpolation">collection</span><span class="token string-interpolation interpolation punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token string-interpolation interpolation">batch</span><span class="token string-interpolation interpolation punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token string-interpolation interpolation">failed_objects</span><span class="token string-interpolation interpolation punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token string-interpolation interpolation punctuation" style="color:rgb(248, 248, 242)">}</span><span class="token string-interpolation string" style="color:rgb(255, 121, 198)"> objects failed."</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><br></span></code></pre></div></div>
<p>That is the whole pattern. No <code>batch_size</code>, no <code>concurrent_requests</code>, no tuning. The <code>stream()</code> context manager opens the persistent connection, the server sets the rate, errors stream back asynchronously without interrupting the flow.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="error-handling-and-retries">Error handling and retries<a href="#error-handling-and-retries" class="hash-link" aria-label="Direct link to Error handling and retries" title="Direct link to Error handling and retries" translate="no">​</a></h2>
<p>The most common bug in production import scripts is treating a 200 response as proof of success. It is not. A 200 means your request reached the server and was accepted. It does not mean every object was written. Vectorizer errors, schema mismatches, and rate-limit responses from upstream embedding APIs all show up as per-object failures inside an otherwise-happy batch response.</p>
<p>The Python client surfaces three things on every batch:</p>
<ul>
<li class=""><code>batch.failed_objects</code> — every object that failed, with the error attached</li>
<li class=""><code>batch.failed_references</code> — every cross-reference that failed</li>
<li class=""><code>batch.number_errors</code> — running count inside the context manager</li>
</ul>
<p>Treat <code>failed_objects</code> as a queue. Write it to a file, retry it, and if it fails again on the same error, move it to a dead-letter location so the rest of your import does not stall behind one broken row.</p>
<p>Here is a retry-with-checkpoint pattern that holds up in production:</p>
<div class="language-python codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-python codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">import</span><span class="token plain"> json</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">from</span><span class="token plain"> weaviate</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">util </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">import</span><span class="token plain"> generate_uuid5</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">with</span><span class="token plain"> collection</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">batch</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">stream</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token plain"> </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">as</span><span class="token plain"> batch</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">for</span><span class="token plain"> row </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">in</span><span class="token plain"> iter_rows</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">        batch</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">add_object</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">            properties</span><span class="token operator">=</span><span class="token plain">row</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">            uuid</span><span class="token operator">=</span><span class="token plain">generate_uuid5</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain">row</span><span class="token punctuation" style="color:rgb(248, 248, 242)">[</span><span class="token string" style="color:rgb(255, 121, 198)">"source_id"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">]</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">        </span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">with</span><span class="token plain"> </span><span class="token builtin" style="color:rgb(189, 147, 249)">open</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token string" style="color:rgb(255, 121, 198)">"failed.jsonl"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> </span><span class="token string" style="color:rgb(255, 121, 198)">"a"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token plain"> </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">as</span><span class="token plain"> f</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">for</span><span class="token plain"> obj </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">in</span><span class="token plain"> collection</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">batch</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">failed_objects</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">        f</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">write</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain">json</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">dumps</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token punctuation" style="color:rgb(248, 248, 242)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">            </span><span class="token string" style="color:rgb(255, 121, 198)">"properties"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"> obj</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">object_</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">properties</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">            </span><span class="token string" style="color:rgb(255, 121, 198)">"error"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"> obj</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">message</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">        </span><span class="token punctuation" style="color:rgb(248, 248, 242)">}</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token plain"> </span><span class="token operator">+</span><span class="token plain"> </span><span class="token string" style="color:rgb(255, 121, 198)">"\n"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><br></span></code></pre></div></div>
<p>Two things make this safe to re-run. First, <code>generate_uuid5</code> produces the same UUID for the same <code>source_id</code> every time, so a retry overwrites instead of duplicating. Second, errors land in a file you can re-import after fixing the underlying issue. No silent loss, no double-billing on embeddings.</p>
<p><img decoding="async" loading="lazy" alt="Retry-with-checkpoint flow showing successful writes to Weaviate alongside a failure branch that captures failed_objects to a JSONL file, retries with deterministic UUIDs, and dead-letters repeat failures." src="/assets/images/retry-checkpoint-flow-72dec1000e327ed02ae6119f33354733.png" width="2400" height="1064" class="img_ev3q"></p>
<p>Common failure modes and what to do about them:</p>
<table><thead><tr><th>Symptom</th><th>Likely cause</th><th>Fix</th></tr></thead><tbody><tr><td>HTTP 200, objects missing</td><td>Vectorizer rate-limited the request</td><td>Inspect <code>failed_objects</code>, retry the failed subset</td></tr><tr><td>Memory blow-up on the client</td><td>Loading the entire dataset before streaming</td><td>Stream from disk or a DB cursor, do not pre-load</td></tr><tr><td>Duplicate objects after a retry</td><td>Fresh random UUIDs on each run</td><td>Use <code>generate_uuid5</code> from a stable source key</td></tr><tr><td>Empty vectors after import</td><td>Vectorizer module not configured on the collection</td><td>Check the collection config before re-running</td></tr></tbody></table>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="ingesting-through-the-mcp-server">Ingesting through the MCP server<a href="#ingesting-through-the-mcp-server" class="hash-link" aria-label="Direct link to Ingesting through the MCP server" title="Direct link to Ingesting through the MCP server" translate="no">​</a></h2>
<p>Weaviate ships a built-in <a href="https://docs.weaviate.io/weaviate/configuration/mcp-server" target="_blank" rel="noopener noreferrer" class="">MCP server</a> (preview, added in v1.37.1) that lets an LLM or IDE assistant — Claude Code, Cursor, VS Code — read and write your instance over the <a href="https://modelcontextprotocol.io/" target="_blank" rel="noopener noreferrer" class="">Model Context Protocol</a>. Enable it with <code>MCP_SERVER_ENABLED=true</code>, opt into writes with <code>MCP_SERVER_WRITE_ACCESS_ENABLED=true</code>, and the server exposes a <code>weaviate-objects-upsert</code> tool that creates or updates objects from inside a conversation. It runs on the same port as the REST API and respects RBAC, so there is nothing extra to deploy.</p>
<p>This is the right tool when an agent needs to write a few records as it works — persisting agent memory, syncing a small collection, or fixing up a handful of objects without leaving your editor.</p>
<p>It is not an ingestion pipeline. Every object is assembled by the model and handed over as a tool call, so you are bound by the context window and per-call latency, with none of the backpressure, streaming, or retry-checkpoint machinery from the sections above. Past a few dozen objects, reach for <code>collection.batch.stream()</code> (or your client's batch API) and leave the MCP server for the conversational, small-batch writes it is built for.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="choosing-data-types-before-you-import">Choosing data types before you import<a href="#choosing-data-types-before-you-import" class="hash-link" aria-label="Direct link to Choosing data types before you import" title="Direct link to Choosing data types before you import" translate="no">​</a></h2>
<p>Schema decisions cost ten times more to fix after the import has run. Get them right the first time.</p>
<p>The ones that matter most at import time:</p>
<ul>
<li class=""><strong><code>text</code> with the right tokenization.</strong> Tokenization decides which BM25 queries match which records. The default is fine for English prose. For product codes, URLs, or anything where the literal string matters, switch to <code>field</code> tokenization. The <a href="https://docs.weaviate.io/weaviate/tutorials/tokenization" target="_blank" rel="noopener noreferrer" class="">tokenization tutorial</a> walks through the trade-offs.</li>
<li class=""><strong><code>uuid</code> for foreign keys.</strong> Indexed for fast filtering, validated at insert time, and rendered as a real UUID in your client rather than a string.</li>
<li class=""><strong><code>int</code> vs <code>number</code>.</strong> Use <code>int</code> for counts and IDs. Use <code>number</code> for prices and ratios. Mixing them up forces casts in every query.</li>
<li class=""><strong>Reference types</strong> for relationships you actually filter on. Do not flatten everything into one big nested object if you query the related fields independently.</li>
</ul>
<p>The full list is in the <a href="https://docs.weaviate.io/weaviate/config-refs/datatypes" target="_blank" rel="noopener noreferrer" class="">data types reference</a>.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="blobhash-store-the-embedding-skip-the-bytes"><code>blobHash</code>: store the embedding, skip the bytes<a href="#blobhash-store-the-embedding-skip-the-bytes" class="hash-link" aria-label="Direct link to blobhash-store-the-embedding-skip-the-bytes" title="Direct link to blobhash-store-the-embedding-skip-the-bytes" translate="no">​</a></h3>
<p>If you are importing media — images, audio, video, PDFs — this is the data type to know.</p>
<p>A regular <code>blob</code> stores the full base64 payload on disk. A <code>blobHash</code> does not. It sends the raw bytes through the vectorizer at import time so the model sees the actual media, then drops everything but a SHA-256 hash. The vector index keeps the embedding. The blob storage keeps a 32-byte fingerprint.</p>
<div class="language-json codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-json codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token punctuation" style="color:rgb(248, 248, 242)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">  </span><span class="token property">"properties"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">[</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    </span><span class="token punctuation" style="color:rgb(248, 248, 242)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">      </span><span class="token property">"name"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:rgb(255, 121, 198)">"product_image"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">      </span><span class="token property">"dataType"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">[</span><span class="token string" style="color:rgb(255, 121, 198)">"blobHash"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">]</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    </span><span class="token punctuation" style="color:rgb(248, 248, 242)">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">  </span><span class="token punctuation" style="color:rgb(248, 248, 242)">]</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token punctuation" style="color:rgb(248, 248, 242)">}</span><br></span></code></pre></div></div>
<p>The practical impact: a 10 TB image corpus shrinks to a few gigabytes of hashes plus the vector index. Similarity search behaves exactly the same way it would with a <code>blob</code>. You just do not pay to store the original bytes inside Weaviate. Keep those in object storage where they belong.</p>
<p><img decoding="async" loading="lazy" alt="Side-by-side diagram comparing blob and blobHash. Both data types send raw bytes through the same vectorizer, but blob persists the full base64 payload while blobHash retains only a 32-byte SHA-256 hash — shrinking a 10 TB image corpus to a few gigabytes stored inside Weaviate." src="/assets/images/blobhash-vs-blob-1e8b10aada0f234bc156ac74b623e2fc.png" width="1800" height="1967" class="img_ev3q"></p>
<p>There is one more nice property. When you update an object, the new base64 is hashed and compared to the stored hash before anything else happens. If the hash matches, Weaviate skips re-vectorization entirely. That alone pays for itself the first time someone re-runs an import pipeline by mistake.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="pdf-vectorization-without-the-ocr-pipeline">PDF vectorization without the OCR pipeline<a href="#pdf-vectorization-without-the-ocr-pipeline" class="hash-link" aria-label="Direct link to PDF vectorization without the OCR pipeline" title="Direct link to PDF vectorization without the OCR pipeline" translate="no">​</a></h2>
<p>For most readers, the practical question is "how do I ingest a folder of PDFs without writing an OCR pipeline." The shortest answer is to spin up a Weaviate Cloud trial and use Weaviate Embeddings.</p>
<p>Weaviate Embeddings has a multimodal model designed for image-based document retrieval. You hand it a page image, it produces a vector. No OCR step. No layout detection. No text extraction. Tables, charts, scanned forms, mixed-language documents all go in the same way. This is cloud-only, but it is the lowest-friction path for trying PDF retrieval on a real dataset and works well for collections up to a few hundred thousand pages without any architectural decisions on your part.</p>
<p>Another ready-made option is Google's <code>multi2vec-google</code> (with <code>gemini-embedding-2</code> at 3072 dimensions), enabled by default on Weaviate Cloud. It follows the same workflow: you render pages to images and embed those. The module takes image input, not raw PDF files, so the rasterization step is the same as with Weaviate Embeddings.</p>
<p>If you are self-hosting at scale and document layout matters, look at the <a href="https://docs.weaviate.io/weaviate/recipes/multi-vector-colipali-rag" target="_blank" rel="noopener noreferrer" class="">multi-vector ColPali recipe</a>. It uses a vision-language model to produce multiple vectors per page and skips chunking entirely. More moving parts, but it is the state of the art for retrieval over visually rich documents.</p>
<p>All three paths live in the same place — the <a href="https://docs.weaviate.io/weaviate/model-providers" target="_blank" rel="noopener noreferrer" class="">model providers reference</a>.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="multimodal-ingestion-text-image-audio-video">Multimodal ingestion: text, image, audio, video<a href="#multimodal-ingestion-text-image-audio-video" class="hash-link" aria-label="Direct link to Multimodal ingestion: text, image, audio, video" title="Direct link to Multimodal ingestion: text, image, audio, video" translate="no">​</a></h2>
<p>Multimodal in Weaviate is not a separate product. It is a vectorizer module on the collection. You declare which model the collection uses, you import objects with media properties (ideally as <code>blobHash</code>), and you query across modalities with the same client you already have.</p>
<p>Coverage by provider:</p>
<table><thead><tr><th>Provider</th><th>Module</th><th>Text</th><th>Image</th><th>Audio</th><th>Video</th></tr></thead><tbody><tr><td>Weaviate Embeddings</td><td>native (WCD)</td><td>✓</td><td>✓</td><td></td><td></td></tr><tr><td>Google</td><td><code>multi2vec-google</code></td><td>✓</td><td>✓</td><td>✓</td><td>✓</td></tr><tr><td>Voyage AI</td><td><code>multi2vec-voyageai</code></td><td>✓</td><td>✓</td><td></td><td>✓</td></tr><tr><td>Jina AI</td><td><code>multi2vec-jinaai</code></td><td>✓</td><td>✓</td><td></td><td></td></tr><tr><td>Cohere</td><td><code>multi2vec-cohere</code></td><td>✓</td><td>✓</td><td></td><td></td></tr><tr><td>NVIDIA</td><td><code>multi2vec-nvidia</code></td><td>✓</td><td>✓</td><td></td><td></td></tr><tr><td>CLIP (self-hosted)</td><td><code>multi2vec-clip</code></td><td>✓</td><td>✓</td><td></td><td></td></tr><tr><td>ImageBind (self-hosted)</td><td><code>multi2vec-bind</code></td><td>✓</td><td>✓</td><td></td><td></td></tr></tbody></table>
<p>A concrete scenario. You are building search for an e-commerce catalog. Every product has a name, a description, three photos, and a fifteen-second demo video. You want one query — "compact wireless earbuds with active noise cancellation" — to find the right product whether the relevant signal is in the text, the photo, or the video.</p>
<p>You declare one collection that uses <code>multi2vec-google</code> across named vectors: a text vector over the name and description, plus a separate <code>blobHash</code> vector for the product image and another for the demo video. Each <code>blobHash</code> property needs its own named vector — once Weaviate replaces the raw bytes with a hash, they can no longer be re-vectorized alongside other fields, so the schema keeps them apart. A single multi-target query then ranks across all three vectors at once: one collection, one query, three modalities — and the media bytes are never stored twice inside Weaviate.</p>
<p>Full setup details for every provider are in the <a href="https://docs.weaviate.io/weaviate/model-providers" target="_blank" rel="noopener noreferrer" class="">model providers reference</a>.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="a-checklist-before-you-press-go">A checklist before you press go<a href="#a-checklist-before-you-press-go" class="hash-link" aria-label="Direct link to A checklist before you press go" title="Direct link to A checklist before you press go" translate="no">​</a></h2>
<ol>
<li class="">Pick data types deliberately. <code>blobHash</code> for any media you do not need to retrieve raw. <code>field</code> tokenization for any text where the literal string matters.</li>
<li class="">Pick the vectorizer at the collection level, not in your import script. Weaviate Embeddings is the easiest default on Weaviate Cloud.</li>
<li class="">Use deterministic UUIDs (<code>generate_uuid5</code> from a stable source key) so retries are idempotent.</li>
<li class="">Use server-side batching via <code>collection.batch.stream()</code> if you are on the Python client.</li>
<li class="">Log <code>failed_objects</code> to a dead-letter file. Do not just print them.</li>
<li class="">Checkpoint progress for large jobs so a crash does not cost you the whole run.</li>
<li class="">If you are importing media at scale, keep the source bytes in object storage and let Weaviate keep the hash, not the file.</li>
</ol>
<p>Do these seven things and you will not be the team rewriting their import script for the third time next quarter.</p>
<p>The fastest way to try any of this is a <a href="https://console.weaviate.cloud/" target="_blank" rel="noopener noreferrer" class="">free Weaviate Cloud trial</a> paired with Weaviate Embeddings. No infrastructure to manage, no embedding API keys, and every snippet in this post runs against it without modification. The <a href="https://docs.weaviate.io/weaviate/tutorials/import" target="_blank" rel="noopener noreferrer" class="">import tutorial</a> is a good next stop once you have a cluster up.</p>
<!-- -->
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="ready-to-start-building">Ready to start building?<a href="#ready-to-start-building" class="hash-link" aria-label="Direct link to Ready to start building?" title="Direct link to Ready to start building?" translate="no">​</a></h2>
<p>Check out the <a href="https://docs.weaviate.io/weaviate/quickstart" target="_blank" rel="noopener noreferrer" class="">Quickstart tutorial</a>, or <a href="https://console.weaviate.cloud/?utm_source=blog&amp;utm_medium=website&amp;utm_campaign=blog_signup&amp;utm_content=data-import-best-practices&amp;utm_term=ready-to-start-building" target="_blank" rel="noopener noreferrer">sign up for a free Weaviate Cloud account</a>.</p>
<!-- -->
]]></content:encoded>
            <category>how-to</category>
            <category>engineering</category>
            <category>concepts</category>
        </item>
        <item>
            <title><![CDATA[Weaviate Cloud is now free to start]]></title>
            <link>https://weaviate.io/blog/weaviate-free-tier</link>
            <guid>https://weaviate.io/blog/weaviate-free-tier</guid>
            <pubDate>Wed, 17 Jun 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[Weaviate Cloud is now free to start across the entire product suite.]]></description>
            <content:encoded><![CDATA[<p><img decoding="async" loading="lazy" alt="Hero image" src="/assets/images/hero-7e23f1bcec767c4354a06f1686768a05.png" width="1200" height="630" class="img_ev3q"></p>
<p>For years, the most common question we got was some version of "Does Weaviate have a free tier?" And for years, my sincere answer was a little awkward: Weaviate has always been free. It's open source, and anyone can run Weaviate on their local machines or own clouds without paying us a cent.</p>
<p>And people do, at an incredible scale. Today, we see many millions of active Weaviate databases running every single month, and our client downloads are rapidly approaching double-digit millions.</p>
<p>So whenever someone asked for a free tier on Weaviate Cloud, part of me wanted to say: “You already have one, go run it yourself.” For a long time, this felt like a complete and principled answer. We didn't want to build a watered-down hosted version just to have a "Free" button on the pricing page when the most powerful free option, the actual open-source database, was already sitting right there.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="what-changed">What changed<a href="#what-changed" class="hash-link" aria-label="Direct link to What changed" title="Direct link to What changed" translate="no">​</a></h2>
<p>Then we stopped being only a database.</p>
<p>Over the past two years, Weaviate grew into a platform. We built the <a href="https://weaviate.io/product/query-agent" target="_blank" rel="noopener noreferrer" class="">Query Agent</a> so you can ask questions of your data in natural language without orchestrating retrieval yourself. These aren't things you spin up from a docker run, but cloud-native services that we operate, scale and maintain.</p>
<p>So while "Just run the open source version" is sound advice for the database, it doesn't work for Query Agent because that is a cloud service. And we introduced free tiers for these products so that all of our products are free to try. Despite this, the managed Weaviate database on Cloud remained without complete parity in this respect and offered a time-limited sandbox.</p>
<p>This didn’t quite sit right, because if we are going to build and scale a platform, the way in should be free across its entirety.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="free-tiers-across-the-whole-platform">Free tiers across the whole platform<a href="#free-tiers-across-the-whole-platform" class="hash-link" aria-label="Direct link to Free tiers across the whole platform" title="Direct link to Free tiers across the whole platform" translate="no">​</a></h2>
<p>So that's what we're announcing today. Weaviate Cloud is now free to start across the entire product suite. The Database and Query Agent are all available as free tiers.</p>
<p>The Weaviate Cloud managed database is now genuinely free, without a credit card or time expiration. It’s the same Weaviate you know and love, with enough room to build a serious prototype, and stays on as long as you’re using it.</p>
<p>(If you're curious about the exact allowances, they're all on the <a href="https://weaviate.io/pricing" target="_blank" rel="noopener noreferrer" class="">pricing page</a>.)</p>
<p>This is the parity we've wanted for a while across all of our products and we are ecstatic to share the change with you.</p>
<p>That shift from "free until the clock runs out" to "free as long as it's useful to you" is the right direction. A free tier should be a place you can actually settle into and build and not a sprint against an expiry date.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="when-youre-ready-for-more">When you're ready for more<a href="#when-youre-ready-for-more" class="hash-link" aria-label="Direct link to When you're ready for more" title="Direct link to When you're ready for more" translate="no">​</a></h2>
<p>At some point your project outgrows the free tier, with more data, traffic, and real users. When that happens, you can easily upgrade your free cluster to a pay-as-you-go cluster that can scale up. No migration or re-architecting is required, and you can ship what you’ve prototyped.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="start-building">Start building<a href="#start-building" class="hash-link" aria-label="Direct link to Start building" title="Direct link to Start building" translate="no">​</a></h2>
<p>If you've been waiting for a reason to try Weaviate Cloud in any of our products, this is the moment: Go build something. We can't wait to see what you make.</p>
<p>- <a href="https://console.weaviate.cloud/" target="_blank" rel="noopener noreferrer" class="">Sign up for free</a><br>
<!-- -->- <a href="https://docs.weaviate.io/cloud/quickstart" target="_blank" rel="noopener noreferrer" class="">Quickstart guide</a><br>
<!-- -->- <a href="https://weaviate.io/pricing" target="_blank" rel="noopener noreferrer" class="">See what's included</a></p>
<!-- -->
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="ready-to-start-building">Ready to start building?<a href="#ready-to-start-building" class="hash-link" aria-label="Direct link to Ready to start building?" title="Direct link to Ready to start building?" translate="no">​</a></h2>
<p>Check out the <a href="https://docs.weaviate.io/weaviate/quickstart" target="_blank" rel="noopener noreferrer" class="">Quickstart tutorial</a>, or <a href="https://console.weaviate.cloud/?utm_source=blog&amp;utm_medium=website&amp;utm_campaign=blog_signup&amp;utm_content=weaviate-free-tier&amp;utm_term=ready-to-start-building" target="_blank" rel="noopener noreferrer">sign up for a free Weaviate Cloud account</a>.</p>
<!-- -->
]]></content:encoded>
            <category>release</category>
        </item>
        <item>
            <title><![CDATA[Leveling up Weaviate Cloud security: Expanding role-based access control for Cloud console]]></title>
            <link>https://weaviate.io/blog/rbac-overview</link>
            <guid>https://weaviate.io/blog/rbac-overview</guid>
            <pubDate>Thu, 28 May 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[Weaviate Cloud now supports more granular role-based access control with new Editor and Viewer roles for improved security and organizational management.]]></description>
            <content:encoded><![CDATA[<p><img decoding="async" loading="lazy" alt="Leveling up Weaviate Cloud security" src="/assets/images/hero-229c3b8452ed90541cf952c6692901f7.png" width="1200" height="630" class="img_ev3q"></p>
<p>You can now assign more granular roles to users in your Weaviate Cloud organization. We are expanding role-based access control (RBAC) for the Cloud console with two new roles — <strong>Editor</strong> and <strong>Viewer</strong> — that add to the existing <strong>Owner</strong> and <strong>Admin</strong> roles, giving organizations more control over resource access.</p>
<p>Role-based access control is a security best practice and a standard feature in modern cloud platforms. It provides a structured way to grant, organize, and delegate permissions across the people and applications working with your cloud resources. RBAC reduces the risk of accidental changes, limits the blast radius of mistakes, and gives security and platform teams the clarity they need to scale Weaviate Cloud usage across an organization.</p>
<p>By assigning Editor or Viewer roles instead of sharing full access, organizations can apply the principle of least privilege, ensuring team members have only the access they need to do their jobs. This applies whether you're a small team of developers or an enterprise rolling out Weaviate across multiple business units.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="weaviate-cloud-roles-and-use-cases">Weaviate Cloud roles and use cases<a href="#weaviate-cloud-roles-and-use-cases" class="hash-link" aria-label="Direct link to Weaviate Cloud roles and use cases" title="Direct link to Weaviate Cloud roles and use cases" translate="no">​</a></h2>
<p>Within a Weaviate Cloud organization, every user can be assigned one of four roles. Each role grants a specific set of permissions across organization settings, billing, cluster management, and access to cluster data.</p>
<table><thead><tr><th style="text-align:left">Owner</th><th style="text-align:left">Admin</th></tr></thead><tbody><tr><td style="text-align:left">Full access to everything in the organization, including billing, user management, and the ability to invite other users as Owners. The person who creates the organization is automatically assigned this role. <br><br> Owners are the only role that can promote other users to Owner. Typically reserved for the small group of people responsible for the organization end-to-end.</td><td style="text-align:left">Manages clusters, billing, and day-to-day organization activity. Admins can invite new users to the organization (but not as Owners) and have full control over cluster creation, configuration, and deletion. <br><br> This is the right role for senior engineers, platform leads, or anyone who needs to operate Weaviate Cloud without the ability to reshape ownership.</td></tr><tr><td style="text-align:left"><strong>Editor</strong> <em>(New)</em></td><td style="text-align:left"><strong>Viewer</strong> <em>(New)</em></td></tr><tr><td style="text-align:left">Manages clusters without touching billing or user invitations. Editors can create, configure, modify, and delete clusters but cannot change billing information or invite new users to the organization. <br><br> This role fits engineers building on Weaviate day-to-day who don't need to manage the organization itself.</td><td style="text-align:left">Read-only access. Viewers can see clusters, configurations, and organization details, but cannot make any changes. <br><br> This is the right role for stakeholders who need visibility — security reviewers, finance partners, or observers from other teams — without the ability to alter anything.</td></tr></tbody></table>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="how-to-manage-roles-in-weaviate-cloud">How to manage roles in Weaviate Cloud<a href="#how-to-manage-roles-in-weaviate-cloud" class="hash-link" aria-label="Direct link to How to manage roles in Weaviate Cloud" title="Direct link to How to manage roles in Weaviate Cloud" translate="no">​</a></h2>
<p>Managing roles in Weaviate Cloud takes just a few clicks.</p>
<ol>
<li class=""><strong>Open your organization menu.</strong> At the top of the Weaviate Cloud console, click the <em>Organization</em> dropdown.</li>
<li class=""><strong>Select Organization settings.</strong> From the dropdown, choose <em>Organization settings</em> to open your organization's management page.</li>
<li class=""><strong>Manage users and roles.</strong> Under the <em>Users and Access</em> section, you'll see every member of your organization, their assigned role, and a description of what each role can do. From here you can:<!-- -->
<ul>
<li class="">Click <em>+ Add User</em> to invite a new member and assign their role during invitation</li>
<li class="">Change an existing user's role using the role selector</li>
<li class="">Remove a user from the organization</li>
</ul>
</li>
</ol>
<p>Changes take effect immediately. Users will see their new permissions on their next action in the console.</p>
<div class="theme-admonition theme-admonition-note admonition_xJq3 alert alert--secondary"><div class="admonitionHeading_Gvgb"><span class="admonitionIcon_Rf37"><svg viewBox="0 0 14 16"><path fill-rule="evenodd" d="M6.3 5.69a.942.942 0 0 1-.28-.7c0-.28.09-.52.28-.7.19-.18.42-.28.7-.28.28 0 .52.09.7.28.18.19.28.42.28.7 0 .28-.09.52-.28.7a1 1 0 0 1-.7.3c-.28 0-.52-.11-.7-.3zM8 7.99c-.02-.25-.11-.48-.31-.69-.2-.19-.42-.3-.69-.31H6c-.27.02-.48.13-.69.31-.2.2-.3.44-.31.69h1v3c.02.27.11.5.31.69.2.2.42.31.69.31h1c.27 0 .48-.11.69-.31.2-.19.3-.42.31-.69H8V7.98v.01zM7 2.3c-3.14 0-5.7 2.54-5.7 5.68 0 3.14 2.56 5.7 5.7 5.7s5.7-2.55 5.7-5.7c0-3.15-2.56-5.69-5.7-5.69v.01zM7 .98c3.86 0 7 3.14 7 7s-3.14 7-7 7-7-3.12-7-7 3.14-7 7-7z"></path></svg></span>note</div><div class="admonitionContent_BuS1"><p>Every organization must have at least one Owner at all times. If you're the only Owner, you'll need to assign Owner permissions to another member before you can leave or delete the organization.</p></div></div>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="learn-more">Learn more<a href="#learn-more" class="hash-link" aria-label="Direct link to Learn more" title="Direct link to Learn more" translate="no">​</a></h2>
<p>If you're ready to start using granular roles in your own organization, sign in to Weaviate Cloud and head to your organization settings. To dive deeper, check out the <a href="https://docs.weaviate.io/cloud/platform/users-and-organizations#user-roles" target="_blank" rel="noopener noreferrer">product documentation</a>.</p>
<p>Have questions or feedback? Join the conversation in our Community Forums or reach us at <a href="mailto:support@weaviate.io" target="_blank" rel="noopener noreferrer" class="">support@weaviate.io</a>.</p>]]></content:encoded>
            <category>security</category>
            <category>cloud</category>
            <category>rbac</category>
        </item>
        <item>
            <title><![CDATA[Build a Coding Assistant with Weaviate MCP: RAG over Code & Docs]]></title>
            <link>https://weaviate.io/blog/coding-assistant-weaviate-mcp</link>
            <guid>https://weaviate.io/blog/coding-assistant-weaviate-mcp</guid>
            <pubDate>Thu, 21 May 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[Use Weaviate's built-in MCP server to give Claude Code, Cursor, and VS Code hybrid search over your codebase and docs. No glue code.]]></description>
            <content:encoded><![CDATA[<p><img decoding="async" loading="lazy" alt="Coding assistant with Weaviate MCP server: hybrid search RAG over your codebase and documentation" src="/assets/images/hero-a54bc5be1b7e33c82e4f7a9ce0aaefc7.png" width="1200" height="630" class="img_ev3q"></p>
<br>
<p>Last week I asked <a href="https://docs.claude.com/en/docs/claude-code/" target="_blank" rel="noopener noreferrer" class="">Claude Code</a> to implement something relatively trivial in my codebase. Three turns in, the conversation used up &gt;80K tokens and Claude was still missing some crucial information I'd forgotten to include. That's the loop you fall into without retrieval: paste too little and the agent guesses, paste too much and pay for context the agent isn't using.</p>
<p>Most teams solve this with <a class="" href="/blog/introduction-to-rag">RAG</a> over the codebase. The typical setup is a vector database plus a custom MCP server process bridging the two. Weaviate simplifies this: the <a href="https://docs.weaviate.io/weaviate/mcp/mcp-server" target="_blank" rel="noopener noreferrer" class="">MCP server is built into the database</a>, at <code>/v1/mcp</code> on the same port as the REST API. One env var enables it. The same <a href="https://docs.weaviate.io/weaviate/concepts/search/hybrid-search" target="_blank" rel="noopener noreferrer" class="">hybrid search</a> you'd use for any other Weaviate workload powers code retrieval, with the <a href="https://docs.weaviate.io/weaviate/search/bm25" target="_blank" rel="noopener noreferrer" class="">BM25</a> half keeping function identifiers like <code>connect_to_local</code> matchable and the vector half finding semantic intent like "how do I init a client."</p>
<p>This post walks through building a coding assistant on top of that built-in MCP server: ingest a codebase, ingest its docs, connect Claude Code, Cursor, and VS Code, and run real queries. Topics covered:</p>
<ul>
<li class=""><a href="#why-your-coding-assistant-needs-more" class="">Why your coding assistant needs more than its training data</a></li>
<li class=""><a href="#why-weaviate-mcp-fits" class="">Why Weaviate MCP fits this job</a></li>
<li class=""><a href="#step-1-run-weaviate" class="">Step 1: Run Weaviate with MCP enabled</a></li>
<li class=""><a href="#step-2-design-the-schema" class="">Step 2: Design the schema</a></li>
<li class=""><a href="#step-3-ingest-codebase" class="">Step 3: Chunk and ingest the codebase</a></li>
<li class=""><a href="#step-4-ingest-docs" class="">Step 4: Chunk and ingest documentation</a></li>
<li class=""><a href="#step-5-connect-clients" class="">Step 5: Connect Claude Code, Cursor, and VS Code</a></li>
<li class=""><a href="#try-it-out" class="">Try it out</a></li>
<li class=""><a href="#agent-runbook" class="">Agent runbook: autonomous setup</a></li>
</ul>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="why-your-coding-assistant-needs-more">Why your coding assistant needs more than its training data<a href="#why-your-coding-assistant-needs-more" class="hash-link" aria-label="Direct link to Why your coding assistant needs more than its training data" title="Direct link to Why your coding assistant needs more than its training data" translate="no">​</a></h2>
<p>LLMs ship with a fixed cutoff and zero knowledge of your private code. The naive workaround is to dump files into the prompt. That has three problems.</p>
<ul>
<li class="">
<p><strong>Cost</strong>: Tokens in context are billed. Every turn. A 200-file Python project doesn't fit, and even the parts that do are billed continuously while the agent reasons.</p>
</li>
<li class="">
<p><strong>Stale context</strong>: Once a file is in the prompt, it's frozen. If the agent changes a function and then needs to read it again, it has to reload the whole file. There's no live link between the model's view and the on-disk truth.</p>
</li>
<li class="">
<p><strong>Wrong granularity</strong>: Even when files fit, the model spends attention on the wrong parts. Imports. Module-level boilerplate. The function the agent is actually editing competes for context with a hundred lines of <code>from x import y</code>.</p>
</li>
</ul>
<p>Retrieval solves all three. Index the codebase once, store the chunks in a vector database, and let the LLM client pull only what it needs per query. That's RAG. Coding assistants haven't had a clean way to talk to such a database without a custom shim. That's where MCP comes in.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="why-weaviate-mcp-fits">Why Weaviate MCP fits this job<a href="#why-weaviate-mcp-fits" class="hash-link" aria-label="Direct link to Why Weaviate MCP fits this job" title="Direct link to Why Weaviate MCP fits this job" translate="no">​</a></h2>
<p><a href="https://modelcontextprotocol.io/docs/develop/build-server" target="_blank" rel="noopener noreferrer" class="">The Model Context Protocol</a> (MCP) is the standardized way for LLM clients like Claude Code, Cursor, and VS Code to call out to external tools. Weaviate <code>v1.37.1</code> exposes its core operations as MCP tools directly, on a <a href="https://modelcontextprotocol.io/docs/concepts/transports#streamable-http" target="_blank" rel="noopener noreferrer" class="">Streamable HTTP endpoint</a> at <code>/v1/mcp</code>. Four tools are surfaced:</p>
<ul>
<li class=""><code>weaviate-collections-get-config</code> — let the LLM inspect what collections exist and what properties they have</li>
<li class=""><code>weaviate-tenants-list</code> — list tenants when you're using multi-tenancy</li>
<li class=""><code>weaviate-query-hybrid</code> — run hybrid (BM25 + vector) search</li>
<li class=""><code>weaviate-objects-upsert</code> — write objects back, only when write access is enabled</li>
</ul>
<p>Hybrid search is the most concrete reason this stack works for a coding assistant. Code is a mix of identifiers and intent. BM25 nails the identifiers. Vectors nail the intent. A query like "where do we handle retry on 429?" wants both at once: vectors find the semantically related retry code, BM25 anchors on <code>429</code> as an exact token. Pure-vector retrieval drops the integer match. Pure-BM25 misses any wording the user didn't already know. Hybrid wins on this kind of mixed-intent query.</p>
<p>Operational simplicity is the second reason. Competing stacks run an MCP server alongside the vector database. That's a second service to watch in production. Weaviate ships the MCP server inside the database, on the same port, with the same auth. The thing you have to monitor is just Weaviate.</p>
<p>The third reason is <a href="https://docs.weaviate.io/weaviate/manage-collections/multi-tenancy" target="_blank" rel="noopener noreferrer" class="">multi-tenancy</a>. One Weaviate instance can hold many codebases, each isolated as a tenant. For an organization with multiple repos, that's one cluster instead of one-per-team.</p>
<p><code>Weaviate MCP vs function calling</code> comes up as a natural question. Function calling is per-LLM-API. MCP is transport-level: any client that speaks MCP can call any server that speaks MCP, no rewrites. Build the retrieval once, use it from Claude Code, Cursor, and VS Code without translating.</p>
<p><img decoding="async" loading="lazy" alt="Architecture: Claude Code, Cursor, and VS Code connecting via MCP to Weaviate, which ingests source code and documentation chunks" src="/assets/images/architecture-173a7b0887d259eeb9e04535538b7958.png" width="1800" height="900" class="img_ev3q"></p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="step-1-run-weaviate">Step 1: Run Weaviate with MCP enabled<a href="#step-1-run-weaviate" class="hash-link" aria-label="Direct link to Step 1: Run Weaviate with MCP enabled" title="Direct link to Step 1: Run Weaviate with MCP enabled" translate="no">​</a></h2>
<p>The MCP server is disabled by default. Two environment variables turn it on:</p>
<div class="language-yaml codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-yaml codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token comment" style="color:rgb(98, 114, 164)"># docker-compose.yml</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token key atrule">services</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">  </span><span class="token key atrule">weaviate</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    </span><span class="token key atrule">image</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"> cr.weaviate.io/semitechnologies/weaviate</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain">1.38.8</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    </span><span class="token key atrule">ports</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">      </span><span class="token punctuation" style="color:rgb(248, 248, 242)">-</span><span class="token plain"> </span><span class="token string" style="color:rgb(255, 121, 198)">'8080:8080'</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">      </span><span class="token punctuation" style="color:rgb(248, 248, 242)">-</span><span class="token plain"> </span><span class="token string" style="color:rgb(255, 121, 198)">'50051:50051'</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    </span><span class="token key atrule">environment</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">      </span><span class="token key atrule">MCP_SERVER_ENABLED</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"> </span><span class="token string" style="color:rgb(255, 121, 198)">'true'</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">      </span><span class="token key atrule">MCP_SERVER_WRITE_ACCESS_ENABLED</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"> </span><span class="token string" style="color:rgb(255, 121, 198)">'true'</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">      </span><span class="token key atrule">AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"> </span><span class="token string" style="color:rgb(255, 121, 198)">'true'</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">      </span><span class="token key atrule">DEFAULT_VECTORIZER_MODULE</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"> </span><span class="token string" style="color:rgb(255, 121, 198)">'text2vec-openai'</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">      </span><span class="token key atrule">ENABLE_MODULES</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"> </span><span class="token string" style="color:rgb(255, 121, 198)">'text2vec-openai'</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">      </span><span class="token key atrule">OPENAI_APIKEY</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"> $</span><span class="token punctuation" style="color:rgb(248, 248, 242)">{</span><span class="token plain">OPENAI_APIKEY</span><span class="token punctuation" style="color:rgb(248, 248, 242)">}</span><br></span></code></pre></div></div>
<p><code>MCP_SERVER_ENABLED</code> exposes the read tools (config, tenants, hybrid query). <code>MCP_SERVER_WRITE_ACCESS_ENABLED</code> adds the upsert tool, which lets the agent write findings back. Skip it if you only want retrieval.</p>
<p>Honestly, I'd skip it for a while even if you think you want write-back. Read-only MCP covers most of what a coding agent actually does, and you sidestep a class of failure modes where the agent writes nonsense back into your knowledge base. Turn write access on once you have a specific use case that justifies the risk.</p>
<div class="theme-admonition theme-admonition-info admonition_xJq3 alert alert--info"><div class="admonitionHeading_Gvgb"><span class="admonitionIcon_Rf37"><svg viewBox="0 0 14 16"><path fill-rule="evenodd" d="M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"></path></svg></span>Auth for production</div><div class="admonitionContent_BuS1"><p>This example uses <code>AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED: 'true'</code> so the post stays focused on the MCP wiring. For any networked deployment, enable an API key and add <code>Authorization: Bearer &lt;key&gt;</code> to your client config — Weaviate's MCP server respects standard auth and RBAC. See <a href="#going-further" class="">§"Going further"</a> for the RBAC permissions involved.</p></div></div>
<p>Bring it up and confirm the endpoint is alive. Streamable HTTP requires an <code>initialize</code> handshake before any other call, so the liveness probe sends one:</p>
<div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token plain">docker compose up -d</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">curl -sf -X POST http://localhost:8080/v1/mcp \</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">  -H 'Content-Type: application/json' \</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">  -H 'Accept: application/json, text/event-stream' \</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">  -d '{</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    "jsonrpc":"2.0","id":0,"method":"initialize",</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    "params":{</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">      "protocolVersion":"2025-03-26",</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">      "capabilities":{},</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">      "clientInfo":{"name":"curl","version":"1"}</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    }</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">  }'</span><br></span></code></pre></div></div>
<p>A live MCP server returns a JSON-RPC envelope describing the server's capabilities and sets an <code>Mcp-Session-Id</code> response header that subsequent calls must echo back. You don't need to parse the body for a sanity check — a non-empty response is enough. If you get a connection refused or a 404, MCP isn't enabled.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="step-2-design-the-schema">Step 2: Design the schema<a href="#step-2-design-the-schema" class="hash-link" aria-label="Direct link to Step 2: Design the schema" title="Direct link to Step 2: Design the schema" translate="no">​</a></h2>
<p>Two collections, one for code chunks and one for documentation chunks, sharing the same Weaviate instance:</p>
<div class="language-python codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-python codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">import</span><span class="token plain"> weaviate</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">from</span><span class="token plain"> weaviate</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">classes</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">config </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">import</span><span class="token plain"> Property</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> DataType</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> Tokenization</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> Configure</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">client </span><span class="token operator">=</span><span class="token plain"> weaviate</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">connect_to_local</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">client</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">collections</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">create</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    name</span><span class="token operator">=</span><span class="token string" style="color:rgb(255, 121, 198)">"CodeChunks"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    properties</span><span class="token operator">=</span><span class="token punctuation" style="color:rgb(248, 248, 242)">[</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">        Property</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain">name</span><span class="token operator">=</span><span class="token string" style="color:rgb(255, 121, 198)">"content"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> data_type</span><span class="token operator">=</span><span class="token plain">DataType</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">TEXT</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">                 tokenization</span><span class="token operator">=</span><span class="token plain">Tokenization</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">WORD</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">        Property</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain">name</span><span class="token operator">=</span><span class="token string" style="color:rgb(255, 121, 198)">"symbol"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> data_type</span><span class="token operator">=</span><span class="token plain">DataType</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">TEXT</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">                 tokenization</span><span class="token operator">=</span><span class="token plain">Tokenization</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">LOWERCASE</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">        Property</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain">name</span><span class="token operator">=</span><span class="token string" style="color:rgb(255, 121, 198)">"file_path"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> data_type</span><span class="token operator">=</span><span class="token plain">DataType</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">TEXT</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">                 tokenization</span><span class="token operator">=</span><span class="token plain">Tokenization</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">FIELD</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">        Property</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain">name</span><span class="token operator">=</span><span class="token string" style="color:rgb(255, 121, 198)">"language"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> data_type</span><span class="token operator">=</span><span class="token plain">DataType</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">TEXT</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">                 tokenization</span><span class="token operator">=</span><span class="token plain">Tokenization</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">FIELD</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">        Property</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain">name</span><span class="token operator">=</span><span class="token string" style="color:rgb(255, 121, 198)">"repo"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> data_type</span><span class="token operator">=</span><span class="token plain">DataType</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">TEXT</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">                 tokenization</span><span class="token operator">=</span><span class="token plain">Tokenization</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">FIELD</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    </span><span class="token punctuation" style="color:rgb(248, 248, 242)">]</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    vector_config</span><span class="token operator">=</span><span class="token plain">Configure</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">Vectors</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">text2vec_openai</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">client</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">collections</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">create</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    name</span><span class="token operator">=</span><span class="token string" style="color:rgb(255, 121, 198)">"DocChunks"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    properties</span><span class="token operator">=</span><span class="token punctuation" style="color:rgb(248, 248, 242)">[</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">        Property</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain">name</span><span class="token operator">=</span><span class="token string" style="color:rgb(255, 121, 198)">"content"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> data_type</span><span class="token operator">=</span><span class="token plain">DataType</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">TEXT</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">                 tokenization</span><span class="token operator">=</span><span class="token plain">Tokenization</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">WORD</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">        Property</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain">name</span><span class="token operator">=</span><span class="token string" style="color:rgb(255, 121, 198)">"title"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> data_type</span><span class="token operator">=</span><span class="token plain">DataType</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">TEXT</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">                 tokenization</span><span class="token operator">=</span><span class="token plain">Tokenization</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">WORD</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">        Property</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain">name</span><span class="token operator">=</span><span class="token string" style="color:rgb(255, 121, 198)">"source_url"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> data_type</span><span class="token operator">=</span><span class="token plain">DataType</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">TEXT</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">                 tokenization</span><span class="token operator">=</span><span class="token plain">Tokenization</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">FIELD</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    </span><span class="token punctuation" style="color:rgb(248, 248, 242)">]</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    vector_config</span><span class="token operator">=</span><span class="token plain">Configure</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">Vectors</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">text2vec_openai</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><br></span></code></pre></div></div>
<p>The <a href="https://docs.weaviate.io/weaviate/concepts/indexing/inverted-index#tokenization" target="_blank" rel="noopener noreferrer" class="">tokenization choices matter</a>. <code>symbol</code> uses <code>lowercase</code> so <code>connect_to_local</code> is one token instead of three. <code>file_path</code>, <code>language</code>, and <code>repo</code> use <code>field</code> so they match exactly. Prose properties (<code>content</code>, <code>title</code>) use <code>word</code>. If this section feels familiar, the <a class="" href="/blog/tokenization-text-analysis-weaviate">tokenization post</a> explains why each method belongs where.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="step-3-ingest-codebase">Step 3: Chunk and ingest the codebase<a href="#step-3-ingest-codebase" class="hash-link" aria-label="Direct link to Step 3: Chunk and ingest the codebase" title="Direct link to Step 3: Chunk and ingest the codebase" translate="no">​</a></h2>
<p>Naive line-based chunking destroys code. A function split across two chunks loses its signature on one side and its body on the other. The fix is to chunk along syntactic boundaries: one chunk per function, one per class, one per top-level statement.</p>
<p>Python's standard library is enough for Python code (no extra dependency). For other languages, <a href="https://tree-sitter.github.io/tree-sitter/" target="_blank" rel="noopener noreferrer" class="">tree-sitter</a> is the standard choice (10+ languages, AST-aware, fast).</p>
<div class="language-python codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-python codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">import</span><span class="token plain"> ast</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">from</span><span class="token plain"> pathlib </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">import</span><span class="token plain"> Path</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">def</span><span class="token plain"> </span><span class="token function" style="color:rgb(80, 250, 123)">chunk_python_file</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain">path</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"> Path</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token plain"> </span><span class="token operator">-</span><span class="token operator">&gt;</span><span class="token plain"> </span><span class="token builtin" style="color:rgb(189, 147, 249)">list</span><span class="token punctuation" style="color:rgb(248, 248, 242)">[</span><span class="token builtin" style="color:rgb(189, 147, 249)">dict</span><span class="token punctuation" style="color:rgb(248, 248, 242)">]</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    </span><span class="token triple-quoted-string string" style="color:rgb(255, 121, 198)">"""Emit one chunk per top-level function or class."""</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    source </span><span class="token operator">=</span><span class="token plain"> path</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">read_text</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    tree </span><span class="token operator">=</span><span class="token plain"> ast</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">parse</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain">source</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    lines </span><span class="token operator">=</span><span class="token plain"> source</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">splitlines</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    chunks </span><span class="token operator">=</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">[</span><span class="token punctuation" style="color:rgb(248, 248, 242)">]</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">for</span><span class="token plain"> node </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">in</span><span class="token plain"> ast</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">iter_child_nodes</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain">tree</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">        </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">if</span><span class="token plain"> </span><span class="token builtin" style="color:rgb(189, 147, 249)">isinstance</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain">node</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain">ast</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">FunctionDef</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> ast</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">AsyncFunctionDef</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> ast</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">ClassDef</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">            start </span><span class="token operator">=</span><span class="token plain"> node</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">lineno </span><span class="token operator">-</span><span class="token plain"> </span><span class="token number">1</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">            end </span><span class="token operator">=</span><span class="token plain"> node</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">end_lineno</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">            chunks</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">append</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token punctuation" style="color:rgb(248, 248, 242)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">                </span><span class="token string" style="color:rgb(255, 121, 198)">"content"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"> </span><span class="token string" style="color:rgb(255, 121, 198)">"\n"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">join</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain">lines</span><span class="token punctuation" style="color:rgb(248, 248, 242)">[</span><span class="token plain">start</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain">end</span><span class="token punctuation" style="color:rgb(248, 248, 242)">]</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">                </span><span class="token string" style="color:rgb(255, 121, 198)">"symbol"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"> node</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">name</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">                </span><span class="token string" style="color:rgb(255, 121, 198)">"file_path"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"> </span><span class="token builtin" style="color:rgb(189, 147, 249)">str</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain">path</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">                </span><span class="token string" style="color:rgb(255, 121, 198)">"language"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"> </span><span class="token string" style="color:rgb(255, 121, 198)">"python"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">                </span><span class="token string" style="color:rgb(255, 121, 198)">"repo"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"> </span><span class="token string" style="color:rgb(255, 121, 198)">"my-service"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">            </span><span class="token punctuation" style="color:rgb(248, 248, 242)">}</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">return</span><span class="token plain"> chunks</span><br></span></code></pre></div></div>
<p>Ingest with <a href="https://docs.weaviate.io/weaviate/manage-objects/import#server-side-batching" target="_blank" rel="noopener noreferrer" class="">server-side batching</a>. <code>data.ingest()</code> takes any iterable, so a generator expression over the repo streams chunks to the server as they are produced, at whatever pace the server asks for:</p>
<div class="language-python codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-python codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token plain">code_chunks </span><span class="token operator">=</span><span class="token plain"> client</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">collections</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">use</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token string" style="color:rgb(255, 121, 198)">"CodeChunks"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">code_chunks</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">data</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">ingest</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    chunk</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">for</span><span class="token plain"> py_file </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">in</span><span class="token plain"> Path</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token string" style="color:rgb(255, 121, 198)">"./src"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">rglob</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token string" style="color:rgb(255, 121, 198)">"*.py"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">for</span><span class="token plain"> chunk </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">in</span><span class="token plain"> chunk_python_file</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain">py_file</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><br></span></code></pre></div></div>
<div class="theme-admonition theme-admonition-note admonition_xJq3 alert alert--secondary"><div class="admonitionHeading_Gvgb"><span class="admonitionIcon_Rf37"><svg viewBox="0 0 14 16"><path fill-rule="evenodd" d="M6.3 5.69a.942.942 0 0 1-.28-.7c0-.28.09-.52.28-.7.19-.18.42-.28.7-.28.28 0 .52.09.7.28.18.19.28.42.28.7 0 .28-.09.52-.28.7a1 1 0 0 1-.7.3c-.28 0-.52-.11-.7-.3zM8 7.99c-.02-.25-.11-.48-.31-.69-.2-.19-.42-.3-.69-.31H6c-.27.02-.48.13-.69.31-.2.2-.3.44-.31.69h1v3c.02.27.11.5.31.69.2.2.42.31.69.31h1c.27 0 .48-.11.69-.31.2-.19.3-.42.31-.69H8V7.98v.01zM7 2.3c-3.14 0-5.7 2.54-5.7 5.68 0 3.14 2.56 5.7 5.7 5.7s5.7-2.55 5.7-5.7c0-3.15-2.56-5.69-5.7-5.69v.01zM7 .98c3.86 0 7 3.14 7 7s-3.14 7-7 7-7-3.12-7-7 3.14-7 7-7z"></path></svg></span>Requires Python client 4.20+</div></div>
<p>Weaviate vectorizes each chunk on insert via the configured <a href="https://docs.weaviate.io/weaviate/model-providers/openai/embeddings" target="_blank" rel="noopener noreferrer" class=""><code>text2vec-openai</code></a> module, so there's no separate embedding step. Replace the vectorizer with <code>text2vec-voyageai</code> (Voyage's <code>voyage-code-2</code> is purpose-built for code) or <code>text2vec-cohere</code> if you want a different embedding family.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="step-4-ingest-docs">Step 4: Chunk and ingest documentation<a href="#step-4-ingest-docs" class="hash-link" aria-label="Direct link to Step 4: Chunk and ingest documentation" title="Direct link to Step 4: Chunk and ingest documentation" translate="no">​</a></h2>
<p>Prose chunks differently. Headings are real boundaries. A useful default is "split on H2, then on H3 if a section is too long":</p>
<div class="language-python codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-python codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">import</span><span class="token plain"> re</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">def</span><span class="token plain"> </span><span class="token function" style="color:rgb(80, 250, 123)">chunk_markdown</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain">text</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"> </span><span class="token builtin" style="color:rgb(189, 147, 249)">str</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> max_chars</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"> </span><span class="token builtin" style="color:rgb(189, 147, 249)">int</span><span class="token plain"> </span><span class="token operator">=</span><span class="token plain"> </span><span class="token number">1500</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token plain"> </span><span class="token operator">-</span><span class="token operator">&gt;</span><span class="token plain"> </span><span class="token builtin" style="color:rgb(189, 147, 249)">list</span><span class="token punctuation" style="color:rgb(248, 248, 242)">[</span><span class="token builtin" style="color:rgb(189, 147, 249)">str</span><span class="token punctuation" style="color:rgb(248, 248, 242)">]</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    sections </span><span class="token operator">=</span><span class="token plain"> re</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">split</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token string" style="color:rgb(255, 121, 198)">r"(?m)^## "</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> text</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    chunks </span><span class="token operator">=</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">[</span><span class="token punctuation" style="color:rgb(248, 248, 242)">]</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">for</span><span class="token plain"> section </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">in</span><span class="token plain"> sections</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">        </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">if</span><span class="token plain"> </span><span class="token builtin" style="color:rgb(189, 147, 249)">len</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain">section</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token plain"> </span><span class="token operator">&lt;=</span><span class="token plain"> max_chars</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">            chunks</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">append</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain">section</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">strip</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">        </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">else</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">            </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">for</span><span class="token plain"> sub </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">in</span><span class="token plain"> re</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">split</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token string" style="color:rgb(255, 121, 198)">r"(?m)^### "</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> section</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">                chunks</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">append</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain">sub</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">strip</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">return</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">[</span><span class="token plain">c </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">for</span><span class="token plain"> c </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">in</span><span class="token plain"> chunks </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">if</span><span class="token plain"> c</span><span class="token punctuation" style="color:rgb(248, 248, 242)">]</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">doc_chunks </span><span class="token operator">=</span><span class="token plain"> client</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">collections</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">use</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token string" style="color:rgb(255, 121, 198)">"DocChunks"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">doc_chunks</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">data</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">ingest</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    </span><span class="token punctuation" style="color:rgb(248, 248, 242)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">        </span><span class="token string" style="color:rgb(255, 121, 198)">"content"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"> content</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">        </span><span class="token string" style="color:rgb(255, 121, 198)">"title"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"> md_file</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">stem</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">        </span><span class="token string" style="color:rgb(255, 121, 198)">"source_url"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"> </span><span class="token string-interpolation string" style="color:rgb(255, 121, 198)">f"https://docs.example.com/</span><span class="token string-interpolation interpolation punctuation" style="color:rgb(248, 248, 242)">{</span><span class="token string-interpolation interpolation">md_file</span><span class="token string-interpolation interpolation punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token string-interpolation interpolation">stem</span><span class="token string-interpolation interpolation punctuation" style="color:rgb(248, 248, 242)">}</span><span class="token string-interpolation string" style="color:rgb(255, 121, 198)">"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    </span><span class="token punctuation" style="color:rgb(248, 248, 242)">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">for</span><span class="token plain"> md_file </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">in</span><span class="token plain"> Path</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token string" style="color:rgb(255, 121, 198)">"./docs"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">rglob</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token string" style="color:rgb(255, 121, 198)">"*.md"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">for</span><span class="token plain"> content </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">in</span><span class="token plain"> chunk_markdown</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain">md_file</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">read_text</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><br></span></code></pre></div></div>
<p>Two collections, two chunking strategies, one Weaviate instance. The MCP server exposes both through the same <code>weaviate-query-hybrid</code> tool. The agent picks which collection to query.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="step-5-connect-clients">Step 5: Connect Claude Code, Cursor, and VS Code<a href="#step-5-connect-clients" class="hash-link" aria-label="Direct link to Step 5: Connect Claude Code, Cursor, and VS Code" title="Direct link to Step 5: Connect Claude Code, Cursor, and VS Code" translate="no">​</a></h2>
<p>The MCP transport is HTTP, so client config is small. Each client has its own file. All three point at the same Weaviate endpoint.</p>
<p><strong><a href="https://code.claude.com/docs/en/mcp" target="_blank" rel="noopener noreferrer" class="">Claude Code</a></strong> (<code>~/.claude.json</code>):</p>
<div class="language-json codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-json codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token punctuation" style="color:rgb(248, 248, 242)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">  </span><span class="token property">"mcpServers"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    </span><span class="token property">"weaviate"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">      </span><span class="token property">"type"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:rgb(255, 121, 198)">"http"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">      </span><span class="token property">"url"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:rgb(255, 121, 198)">"http://localhost:8080/v1/mcp"</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    </span><span class="token punctuation" style="color:rgb(248, 248, 242)">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">  </span><span class="token punctuation" style="color:rgb(248, 248, 242)">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token punctuation" style="color:rgb(248, 248, 242)">}</span><br></span></code></pre></div></div>
<p>Or via the CLI:</p>
<div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token plain">claude mcp add weaviate http://localhost:8080/v1/mcp --transport http</span><br></span></code></pre></div></div>
<p><strong><a href="https://docs.cursor.com/context/model-context-protocol" target="_blank" rel="noopener noreferrer" class="">Cursor</a></strong> (<code>~/.cursor/mcp.json</code> or project-local <code>.cursor/mcp.json</code>):</p>
<div class="language-json codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-json codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token punctuation" style="color:rgb(248, 248, 242)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">  </span><span class="token property">"mcpServers"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    </span><span class="token property">"weaviate"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">      </span><span class="token property">"url"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:rgb(255, 121, 198)">"http://localhost:8080/v1/mcp"</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    </span><span class="token punctuation" style="color:rgb(248, 248, 242)">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">  </span><span class="token punctuation" style="color:rgb(248, 248, 242)">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token punctuation" style="color:rgb(248, 248, 242)">}</span><br></span></code></pre></div></div>
<p><strong><a href="https://code.visualstudio.com/docs/copilot/customization/mcp-servers" target="_blank" rel="noopener noreferrer" class="">VS Code with Copilot</a></strong> (<code>.vscode/mcp.json</code>):</p>
<div class="language-json codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-json codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token punctuation" style="color:rgb(248, 248, 242)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">  </span><span class="token property">"servers"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    </span><span class="token property">"weaviate"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">      </span><span class="token property">"type"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:rgb(255, 121, 198)">"http"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">      </span><span class="token property">"url"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:rgb(255, 121, 198)">"http://localhost:8080/v1/mcp"</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    </span><span class="token punctuation" style="color:rgb(248, 248, 242)">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">  </span><span class="token punctuation" style="color:rgb(248, 248, 242)">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token punctuation" style="color:rgb(248, 248, 242)">}</span><br></span></code></pre></div></div>
<p>Restart the client. The Weaviate tools (<code>weaviate-query-hybrid</code>, <code>weaviate-collections-get-config</code>, etc.) should appear in the client's tool list. If they don't, check that <code>MCP_SERVER_ENABLED=true</code> is set and that the port is reachable.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="try-it-out">Try it out<a href="#try-it-out" class="hash-link" aria-label="Direct link to Try it out" title="Direct link to Try it out" translate="no">​</a></h2>
<p>Open Claude Code in any directory after the runbook below has finished. Ask something specific to FastAPI internals that a generic model would only paraphrase from training data:</p>
<blockquote>
<p>"How does FastAPI handle dependency injection — show me the actual resolver."</p>
</blockquote>
<p>Without MCP, Claude Code paraphrases the FastAPI <a href="https://fastapi.tiangolo.com/tutorial/dependencies/" target="_blank" rel="noopener noreferrer" class="">dependency injection</a> docs from training. With MCP, it calls <code>weaviate-query-hybrid</code> against <code>CodeChunks</code>, the BM25 half nails identifiers like <code>Depends</code> and <code>solve_dependencies</code>, the vector half pulls in nearby resolver code, and the answer cites real lines from <code>fastapi/dependencies/utils.py</code>.</p>
<p>Try a docs query:</p>
<blockquote>
<p>"When should I use <code>async def</code> versus <code>def</code> in FastAPI route handlers?"</p>
</blockquote>
<p>Same shape, different collection. The agent queries <code>DocChunks</code>, returns the relevant section from FastAPI's <a href="https://fastapi.tiangolo.com/async/" target="_blank" rel="noopener noreferrer" class=""><code>async def</code> versus <code>def</code></a> guide, and answers with the actual recommendation rather than guessing.</p>
<p>The general pattern: the agent decides per-question whether code, docs, or both are relevant, and pulls the chunks that are. Context size stays bounded. The repo can be huge.</p>
<p><img decoding="async" loading="lazy" alt="Hybrid retrieval for code search: BM25 lane matches identifiers, vector lane matches semantic intent, fused result feeds Claude Code" src="/assets/images/hybrid-retrieval-fcce975b20bfaa162179ef48893ba8d1.png" width="1800" height="759" class="img_ev3q"></p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="agent-runbook">Agent runbook: autonomous setup<a href="#agent-runbook" class="hash-link" aria-label="Direct link to Agent runbook: autonomous setup" title="Direct link to Agent runbook: autonomous setup" translate="no">​</a></h3>
<p>The narrative above is for humans. If you are an agent (Claude Code, Cursor, or any MCP-aware assistant) executing this end-to-end, the dropdown below is the contract: ordered steps, full scripts, success criteria. Run them in order. Each step prints a marker the next step can check.</p>
<details class="details_lb9f alert alert--info details_b_Ee" data-collapsed="true"><summary><strong>Autonomous setup runbook</strong> — copy these scripts, run in order</summary><div><div class="collapsibleContent_i85q"><h4 class="anchor anchorTargetStickyNavbar_Vzrq" id="inputs">Inputs<a href="#inputs" class="hash-link" aria-label="Direct link to Inputs" title="Direct link to Inputs" translate="no">​</a></h4><p>This runbook uses <a href="https://github.com/fastapi/fastapi" target="_blank" rel="noopener noreferrer" class="">FastAPI</a> as the demo codebase. It's well-known, ~30K LOC of Python with substantial MkDocs documentation, and matches both chunkers in the script (Python AST for source, heading-aware split for Markdown). Replace the clone target with any other repo to ingest your own.</p><p>Clone the demo repo and define environment variables:</p><div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token plain"># Clone FastAPI as the demo target</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">git clone --depth=1 https://github.com/fastapi/fastapi.git /tmp/fastapi</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">export WEAVIATE_DIR="$HOME/weaviate-code-assistant"   # where docker-compose.yml lives</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">export CODE_DIR="/tmp/fastapi/fastapi"                 # FastAPI Python source</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">export DOCS_DIR="/tmp/fastapi/docs/en/docs"            # FastAPI English MkDocs content</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">export OPENAI_APIKEY="sk-..."                          # required for the text2vec-openai vectorizer</span><br></span></code></pre></div></div><p>If <code>OPENAI_APIKEY</code> is unset, stop and ask. Do not proceed with a placeholder.</p><h4 class="anchor anchorTargetStickyNavbar_Vzrq" id="step-1-provision-and-start-weaviate">Step 1: Provision and start Weaviate<a href="#step-1-provision-and-start-weaviate" class="hash-link" aria-label="Direct link to Step 1: Provision and start Weaviate" title="Direct link to Step 1: Provision and start Weaviate" translate="no">​</a></h4><p>Save the following as <code>$WEAVIATE_DIR/setup.sh</code>, make it executable, and run it. Idempotent: re-running on an already-up instance is a no-op.</p><div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token plain">#!/usr/bin/env bash</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">set -euo pipefail</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">mkdir -p "$WEAVIATE_DIR"</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">cd "$WEAVIATE_DIR"</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">cat &gt; docker-compose.yml &lt;&lt;'YAML'</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">services:</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">  weaviate:</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    image: cr.weaviate.io/semitechnologies/weaviate:1.38.8</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    ports:</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">      - "8080:8080"</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">      - "50051:50051"</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    environment:</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">      MCP_SERVER_ENABLED: 'true'</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">      MCP_SERVER_WRITE_ACCESS_ENABLED: 'true'</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">      AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED: 'true'</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">      PERSISTENCE_DATA_PATH: '/var/lib/weaviate'</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">      DEFAULT_VECTORIZER_MODULE: 'text2vec-openai'</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">      ENABLE_MODULES: 'text2vec-openai'</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">      OPENAI_APIKEY: ${OPENAI_APIKEY}</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    volumes:</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">      - weaviate-data:/var/lib/weaviate</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">volumes:</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">  weaviate-data:</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">YAML</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">docker compose up -d</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"># Wait for the REST API to come up (max 60s)</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">for i in {1..30}; do</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">  if curl -sf http://localhost:8080/v1/.well-known/ready &gt; /dev/null; then</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    echo "STEP_1_READY"</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    break</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">  fi</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">  sleep 2</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">done</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"># Verify the MCP endpoint is reachable. Streamable HTTP requires an</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"># initialize handshake first; tools/list then needs the Mcp-Session-Id</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"># header returned by initialize.</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">SID=$(curl -s -i -X POST http://localhost:8080/v1/mcp \</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">  -H 'Content-Type: application/json' \</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">  -H 'Accept: application/json, text/event-stream' \</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">  -d '{"jsonrpc":"2.0","id":0,"method":"initialize","params":{</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">        "protocolVersion":"2025-03-26","capabilities":{},</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">        "clientInfo":{"name":"curl","version":"1"}}}' \</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">  | awk -F': ' 'tolower($1)=="mcp-session-id"{print $2}' | tr -d '\r\n')</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">if [ -z "$SID" ]; then</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">  echo "STEP_1_MCP_FAILED: no Mcp-Session-Id returned. MCP may be disabled."</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">  exit 1</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">fi</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">curl -sf -o /dev/null -X POST http://localhost:8080/v1/mcp \</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">  -H 'Content-Type: application/json' \</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">  -H 'Accept: application/json, text/event-stream' \</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">  -H "Mcp-Session-Id: $SID" \</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' \</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">  &amp;&amp; echo "STEP_1_MCP_OK" \</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">  || { echo "STEP_1_MCP_FAILED"; exit 1; }</span><br></span></code></pre></div></div><p><strong>Success criteria:</strong> stdout contains both <code>STEP_1_READY</code> and <code>STEP_1_MCP_OK</code>. If only <code>STEP_1_READY</code> shows, MCP is disabled or the version is wrong.</p><h4 class="anchor anchorTargetStickyNavbar_Vzrq" id="step-2-create-collections-and-ingest-data">Step 2: Create collections and ingest data<a href="#step-2-create-collections-and-ingest-data" class="hash-link" aria-label="Direct link to Step 2: Create collections and ingest data" title="Direct link to Step 2: Create collections and ingest data" translate="no">​</a></h4><p>Save the following as <code>$WEAVIATE_DIR/ingest.py</code> and run it with <code>python3 ingest.py</code>. Idempotent: collections that already exist are reused; objects are inserted (duplicates may accumulate, see note at end).</p><div class="language-python codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-python codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token comment" style="color:rgb(98, 114, 164)">#!/usr/bin/env python3</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token triple-quoted-string string" style="color:rgb(255, 121, 198)">"""Ingest a codebase and its docs into Weaviate. Run after setup.sh."""</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">import</span><span class="token plain"> ast</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">import</span><span class="token plain"> os</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">import</span><span class="token plain"> re</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">import</span><span class="token plain"> sys</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">from</span><span class="token plain"> pathlib </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">import</span><span class="token plain"> Path</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">import</span><span class="token plain"> weaviate</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">from</span><span class="token plain"> weaviate</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">classes</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">config </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">import</span><span class="token plain"> Property</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> DataType</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> Tokenization</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> Configure</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">CODE_DIR </span><span class="token operator">=</span><span class="token plain"> Path</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain">os</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">environ</span><span class="token punctuation" style="color:rgb(248, 248, 242)">[</span><span class="token string" style="color:rgb(255, 121, 198)">"CODE_DIR"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">]</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">resolve</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">DOCS_DIR </span><span class="token operator">=</span><span class="token plain"> Path</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain">os</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">environ</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">get</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token string" style="color:rgb(255, 121, 198)">"DOCS_DIR"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> CODE_DIR</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">resolve</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">REPO_LABEL </span><span class="token operator">=</span><span class="token plain"> CODE_DIR</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">name</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">client </span><span class="token operator">=</span><span class="token plain"> weaviate</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">connect_to_local</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">try</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    </span><span class="token comment" style="color:rgb(98, 114, 164)"># ---- Schema (idempotent) ----</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">if</span><span class="token plain"> </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">not</span><span class="token plain"> client</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">collections</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">exists</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token string" style="color:rgb(255, 121, 198)">"CodeChunks"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">        client</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">collections</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">create</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">            name</span><span class="token operator">=</span><span class="token string" style="color:rgb(255, 121, 198)">"CodeChunks"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">            properties</span><span class="token operator">=</span><span class="token punctuation" style="color:rgb(248, 248, 242)">[</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">                Property</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain">name</span><span class="token operator">=</span><span class="token string" style="color:rgb(255, 121, 198)">"content"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> data_type</span><span class="token operator">=</span><span class="token plain">DataType</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">TEXT</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> tokenization</span><span class="token operator">=</span><span class="token plain">Tokenization</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">WORD</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">                Property</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain">name</span><span class="token operator">=</span><span class="token string" style="color:rgb(255, 121, 198)">"symbol"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> data_type</span><span class="token operator">=</span><span class="token plain">DataType</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">TEXT</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> tokenization</span><span class="token operator">=</span><span class="token plain">Tokenization</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">LOWERCASE</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">                Property</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain">name</span><span class="token operator">=</span><span class="token string" style="color:rgb(255, 121, 198)">"file_path"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> data_type</span><span class="token operator">=</span><span class="token plain">DataType</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">TEXT</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> tokenization</span><span class="token operator">=</span><span class="token plain">Tokenization</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">FIELD</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">                Property</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain">name</span><span class="token operator">=</span><span class="token string" style="color:rgb(255, 121, 198)">"language"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> data_type</span><span class="token operator">=</span><span class="token plain">DataType</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">TEXT</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> tokenization</span><span class="token operator">=</span><span class="token plain">Tokenization</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">FIELD</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">                Property</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain">name</span><span class="token operator">=</span><span class="token string" style="color:rgb(255, 121, 198)">"repo"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> data_type</span><span class="token operator">=</span><span class="token plain">DataType</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">TEXT</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> tokenization</span><span class="token operator">=</span><span class="token plain">Tokenization</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">FIELD</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">            </span><span class="token punctuation" style="color:rgb(248, 248, 242)">]</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">            vector_config</span><span class="token operator">=</span><span class="token plain">Configure</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">Vectors</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">text2vec_openai</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">        </span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">if</span><span class="token plain"> </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">not</span><span class="token plain"> client</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">collections</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">exists</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token string" style="color:rgb(255, 121, 198)">"DocChunks"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">        client</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">collections</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">create</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">            name</span><span class="token operator">=</span><span class="token string" style="color:rgb(255, 121, 198)">"DocChunks"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">            properties</span><span class="token operator">=</span><span class="token punctuation" style="color:rgb(248, 248, 242)">[</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">                Property</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain">name</span><span class="token operator">=</span><span class="token string" style="color:rgb(255, 121, 198)">"content"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> data_type</span><span class="token operator">=</span><span class="token plain">DataType</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">TEXT</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> tokenization</span><span class="token operator">=</span><span class="token plain">Tokenization</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">WORD</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">                Property</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain">name</span><span class="token operator">=</span><span class="token string" style="color:rgb(255, 121, 198)">"title"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> data_type</span><span class="token operator">=</span><span class="token plain">DataType</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">TEXT</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> tokenization</span><span class="token operator">=</span><span class="token plain">Tokenization</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">WORD</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">                Property</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain">name</span><span class="token operator">=</span><span class="token string" style="color:rgb(255, 121, 198)">"source_url"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> data_type</span><span class="token operator">=</span><span class="token plain">DataType</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">TEXT</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> tokenization</span><span class="token operator">=</span><span class="token plain">Tokenization</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">FIELD</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">            </span><span class="token punctuation" style="color:rgb(248, 248, 242)">]</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">            vector_config</span><span class="token operator">=</span><span class="token plain">Configure</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">Vectors</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">text2vec_openai</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">        </span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    </span><span class="token comment" style="color:rgb(98, 114, 164)"># ---- Code: AST-chunk every .py file ----</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    code </span><span class="token operator">=</span><span class="token plain"> client</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">collections</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">use</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token string" style="color:rgb(255, 121, 198)">"CodeChunks"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    code_count </span><span class="token operator">=</span><span class="token plain"> </span><span class="token number">0</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">with</span><span class="token plain"> code</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">batch</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">stream</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token plain"> </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">as</span><span class="token plain"> batch</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">        </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">for</span><span class="token plain"> py </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">in</span><span class="token plain"> CODE_DIR</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">rglob</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token string" style="color:rgb(255, 121, 198)">"*.py"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">            </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">if</span><span class="token plain"> </span><span class="token builtin" style="color:rgb(189, 147, 249)">any</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain">part</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">startswith</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token string" style="color:rgb(255, 121, 198)">"."</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token plain"> </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">or</span><span class="token plain"> part </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">in</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token string" style="color:rgb(255, 121, 198)">"node_modules"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> </span><span class="token string" style="color:rgb(255, 121, 198)">"venv"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> </span><span class="token string" style="color:rgb(255, 121, 198)">".venv"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> </span><span class="token string" style="color:rgb(255, 121, 198)">"__pycache__"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token plain"> </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">for</span><span class="token plain"> part </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">in</span><span class="token plain"> py</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">parts</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">                </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">continue</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">            </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">try</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">                source </span><span class="token operator">=</span><span class="token plain"> py</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">read_text</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain">encoding</span><span class="token operator">=</span><span class="token string" style="color:rgb(255, 121, 198)">"utf-8"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">                tree </span><span class="token operator">=</span><span class="token plain"> ast</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">parse</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain">source</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">            </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">except</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain">SyntaxError</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> UnicodeDecodeError</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">                </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">continue</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">            lines </span><span class="token operator">=</span><span class="token plain"> source</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">splitlines</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">            </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">for</span><span class="token plain"> node </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">in</span><span class="token plain"> ast</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">iter_child_nodes</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain">tree</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">                </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">if</span><span class="token plain"> </span><span class="token builtin" style="color:rgb(189, 147, 249)">isinstance</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain">node</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain">ast</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">FunctionDef</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> ast</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">AsyncFunctionDef</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> ast</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">ClassDef</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">                    chunk </span><span class="token operator">=</span><span class="token plain"> </span><span class="token string" style="color:rgb(255, 121, 198)">"\n"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">join</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain">lines</span><span class="token punctuation" style="color:rgb(248, 248, 242)">[</span><span class="token plain">node</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">lineno </span><span class="token operator">-</span><span class="token plain"> </span><span class="token number">1</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain">node</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">end_lineno</span><span class="token punctuation" style="color:rgb(248, 248, 242)">]</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">                    batch</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">add_object</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain">properties</span><span class="token operator">=</span><span class="token punctuation" style="color:rgb(248, 248, 242)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">                        </span><span class="token string" style="color:rgb(255, 121, 198)">"content"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"> chunk</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">                        </span><span class="token string" style="color:rgb(255, 121, 198)">"symbol"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"> node</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">name</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">                        </span><span class="token string" style="color:rgb(255, 121, 198)">"file_path"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"> </span><span class="token builtin" style="color:rgb(189, 147, 249)">str</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain">py</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">                        </span><span class="token string" style="color:rgb(255, 121, 198)">"language"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"> </span><span class="token string" style="color:rgb(255, 121, 198)">"python"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">                        </span><span class="token string" style="color:rgb(255, 121, 198)">"repo"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"> REPO_LABEL</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">                    </span><span class="token punctuation" style="color:rgb(248, 248, 242)">}</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">                    code_count </span><span class="token operator">+=</span><span class="token plain"> </span><span class="token number">1</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">print</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token string-interpolation string" style="color:rgb(255, 121, 198)">f"STEP_2_CODE_CHUNKS=</span><span class="token string-interpolation interpolation punctuation" style="color:rgb(248, 248, 242)">{</span><span class="token string-interpolation interpolation">code_count</span><span class="token string-interpolation interpolation punctuation" style="color:rgb(248, 248, 242)">}</span><span class="token string-interpolation string" style="color:rgb(255, 121, 198)">"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    </span><span class="token comment" style="color:rgb(98, 114, 164)"># ---- Docs: heading-chunk every .md file ----</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    docs </span><span class="token operator">=</span><span class="token plain"> client</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">collections</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">use</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token string" style="color:rgb(255, 121, 198)">"DocChunks"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    doc_count </span><span class="token operator">=</span><span class="token plain"> </span><span class="token number">0</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">with</span><span class="token plain"> docs</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">batch</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">stream</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token plain"> </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">as</span><span class="token plain"> batch</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">        </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">for</span><span class="token plain"> md </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">in</span><span class="token plain"> DOCS_DIR</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">rglob</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token string" style="color:rgb(255, 121, 198)">"*.md"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">            </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">if</span><span class="token plain"> </span><span class="token builtin" style="color:rgb(189, 147, 249)">any</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain">part</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">startswith</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token string" style="color:rgb(255, 121, 198)">"."</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token plain"> </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">for</span><span class="token plain"> part </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">in</span><span class="token plain"> md</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">parts</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">                </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">continue</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">            </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">try</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">                text </span><span class="token operator">=</span><span class="token plain"> md</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">read_text</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain">encoding</span><span class="token operator">=</span><span class="token string" style="color:rgb(255, 121, 198)">"utf-8"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">            </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">except</span><span class="token plain"> UnicodeDecodeError</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">                </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">continue</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">            sections </span><span class="token operator">=</span><span class="token plain"> re</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">split</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token string" style="color:rgb(255, 121, 198)">r"(?m)^## "</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> text</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">            </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">for</span><span class="token plain"> sec </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">in</span><span class="token plain"> sections</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">                sec </span><span class="token operator">=</span><span class="token plain"> sec</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">strip</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">                </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">if</span><span class="token plain"> </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">not</span><span class="token plain"> sec</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">                    </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">continue</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">                </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">if</span><span class="token plain"> </span><span class="token builtin" style="color:rgb(189, 147, 249)">len</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain">sec</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token plain"> </span><span class="token operator">&gt;</span><span class="token plain"> </span><span class="token number">1500</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">                    </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">for</span><span class="token plain"> sub </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">in</span><span class="token plain"> re</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">split</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token string" style="color:rgb(255, 121, 198)">r"(?m)^### "</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> sec</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">                        sub </span><span class="token operator">=</span><span class="token plain"> sub</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">strip</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">                        </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">if</span><span class="token plain"> sub</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">                            batch</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">add_object</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain">properties</span><span class="token operator">=</span><span class="token punctuation" style="color:rgb(248, 248, 242)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">                                </span><span class="token string" style="color:rgb(255, 121, 198)">"content"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"> sub</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">                                </span><span class="token string" style="color:rgb(255, 121, 198)">"title"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"> md</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">stem</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">                                </span><span class="token string" style="color:rgb(255, 121, 198)">"source_url"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"> </span><span class="token string-interpolation string" style="color:rgb(255, 121, 198)">f"file://</span><span class="token string-interpolation interpolation punctuation" style="color:rgb(248, 248, 242)">{</span><span class="token string-interpolation interpolation">md</span><span class="token string-interpolation interpolation punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token string-interpolation interpolation">resolve</span><span class="token string-interpolation interpolation punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token string-interpolation interpolation punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token string-interpolation interpolation punctuation" style="color:rgb(248, 248, 242)">}</span><span class="token string-interpolation string" style="color:rgb(255, 121, 198)">"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">                            </span><span class="token punctuation" style="color:rgb(248, 248, 242)">}</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">                            doc_count </span><span class="token operator">+=</span><span class="token plain"> </span><span class="token number">1</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">                </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">else</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">                    batch</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">add_object</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain">properties</span><span class="token operator">=</span><span class="token punctuation" style="color:rgb(248, 248, 242)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">                        </span><span class="token string" style="color:rgb(255, 121, 198)">"content"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"> sec</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">                        </span><span class="token string" style="color:rgb(255, 121, 198)">"title"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"> md</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">stem</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">                        </span><span class="token string" style="color:rgb(255, 121, 198)">"source_url"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"> </span><span class="token string-interpolation string" style="color:rgb(255, 121, 198)">f"file://</span><span class="token string-interpolation interpolation punctuation" style="color:rgb(248, 248, 242)">{</span><span class="token string-interpolation interpolation">md</span><span class="token string-interpolation interpolation punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token string-interpolation interpolation">resolve</span><span class="token string-interpolation interpolation punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token string-interpolation interpolation punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token string-interpolation interpolation punctuation" style="color:rgb(248, 248, 242)">}</span><span class="token string-interpolation string" style="color:rgb(255, 121, 198)">"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">                    </span><span class="token punctuation" style="color:rgb(248, 248, 242)">}</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">                    doc_count </span><span class="token operator">+=</span><span class="token plain"> </span><span class="token number">1</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">print</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token string-interpolation string" style="color:rgb(255, 121, 198)">f"STEP_2_DOC_CHUNKS=</span><span class="token string-interpolation interpolation punctuation" style="color:rgb(248, 248, 242)">{</span><span class="token string-interpolation interpolation">doc_count</span><span class="token string-interpolation interpolation punctuation" style="color:rgb(248, 248, 242)">}</span><span class="token string-interpolation string" style="color:rgb(255, 121, 198)">"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">if</span><span class="token plain"> code_count </span><span class="token operator">+</span><span class="token plain"> doc_count </span><span class="token operator">==</span><span class="token plain"> </span><span class="token number">0</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">        </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">print</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token string" style="color:rgb(255, 121, 198)">"STEP_2_FAILED: no chunks ingested. Check CODE_DIR / DOCS_DIR paths."</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> </span><span class="token builtin" style="color:rgb(189, 147, 249)">file</span><span class="token operator">=</span><span class="token plain">sys</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">stderr</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">        sys</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">exit</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token number">2</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">print</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token string" style="color:rgb(255, 121, 198)">"STEP_2_INGEST_OK"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">finally</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    client</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">close</span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><br></span></code></pre></div></div><p><strong>Success criteria:</strong> stdout contains <code>STEP_2_INGEST_OK</code> and the chunk counts are non-zero. If both counts are zero, the input paths point to empty or unsupported content.</p><p><strong>Note on idempotency:</strong> re-running this script appends objects rather than upserting. For a clean re-ingest, delete the collections first:</p><div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token plain">curl -X DELETE http://localhost:8080/v1/schema/CodeChunks</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">curl -X DELETE http://localhost:8080/v1/schema/DocChunks</span><br></span></code></pre></div></div><h4 class="anchor anchorTargetStickyNavbar_Vzrq" id="step-3-wire-up-the-llm-client">Step 3: Wire up the LLM client<a href="#step-3-wire-up-the-llm-client" class="hash-link" aria-label="Direct link to Step 3: Wire up the LLM client" title="Direct link to Step 3: Wire up the LLM client" translate="no">​</a></h4><p>Pick the block matching the agent's host client. All three point at the same Weaviate endpoint.</p><p><strong>Claude Code</strong> (preferred, single command):</p><div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token plain">claude mcp add weaviate http://localhost:8080/v1/mcp --transport http</span><br></span></code></pre></div></div><p>If the <code>claude</code> CLI is not on PATH, write the config directly:</p><div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token plain">python3 -c '</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">import json, os, pathlib</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">p = pathlib.Path(os.path.expanduser("~/.claude.json"))</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">data = json.loads(p.read_text()) if p.exists() else {}</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">data.setdefault("mcpServers", {})["weaviate"] = {</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    "type": "http",</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    "url": "http://localhost:8080/v1/mcp"</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">}</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">p.write_text(json.dumps(data, indent=2))</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">print("STEP_3_CLAUDE_OK")</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">'</span><br></span></code></pre></div></div><p><strong>Cursor</strong> (<code>~/.cursor/mcp.json</code>):</p><div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token plain">python3 -c '</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">import json, os, pathlib</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">p = pathlib.Path(os.path.expanduser("~/.cursor/mcp.json"))</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">p.parent.mkdir(parents=True, exist_ok=True)</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">data = json.loads(p.read_text()) if p.exists() else {}</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">data.setdefault("mcpServers", {})["weaviate"] = {"url": "http://localhost:8080/v1/mcp"}</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">p.write_text(json.dumps(data, indent=2))</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">print("STEP_3_CURSOR_OK")</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">'</span><br></span></code></pre></div></div><p><strong>VS Code with Copilot</strong> (project-local <code>.vscode/mcp.json</code>):</p><div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token plain">mkdir -p .vscode</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">cat &gt; .vscode/mcp.json &lt;&lt;'JSON'</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">{</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">  "servers": {</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    "weaviate": {</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">      "type": "http",</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">      "url": "http://localhost:8080/v1/mcp"</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    }</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">  }</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">}</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">JSON</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">echo "STEP_3_VSCODE_OK"</span><br></span></code></pre></div></div><p><strong>Success criteria:</strong> the appropriate <code>STEP_3_*_OK</code> marker prints, and the next interactive turn surfaces a <code>weaviate-query-hybrid</code> tool in the client's tool list. If the tool does not appear, restart the client.</p><h4 class="anchor anchorTargetStickyNavbar_Vzrq" id="step-4-verify-retrieval-works">Step 4: Verify retrieval works<a href="#step-4-verify-retrieval-works" class="hash-link" aria-label="Direct link to Step 4: Verify retrieval works" title="Direct link to Step 4: Verify retrieval works" translate="no">​</a></h4><p>This block confirms end-to-end retrieval without involving the LLM client. Streamable HTTP again needs the <code>initialize</code> handshake first so the session ID can be reused on the actual <code>tools/call</code>. Replace the query string with something the agent expects to be in the ingested codebase.</p><div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token plain">SID=$(curl -s -i -X POST http://localhost:8080/v1/mcp \</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">  -H 'Content-Type: application/json' \</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">  -H 'Accept: application/json, text/event-stream' \</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">  -d '{"jsonrpc":"2.0","id":0,"method":"initialize","params":{</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">        "protocolVersion":"2025-03-26","capabilities":{},</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">        "clientInfo":{"name":"curl","version":"1"}}}' \</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">  | awk -F': ' 'tolower($1)=="mcp-session-id"{print $2}' | tr -d '\r\n')</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">curl -sX POST http://localhost:8080/v1/mcp \</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">  -H 'Content-Type: application/json' \</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">  -H 'Accept: application/json, text/event-stream' \</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">  -H "Mcp-Session-Id: $SID" \</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">  -d '{</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    "jsonrpc":"2.0",</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    "id":1,</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    "method":"tools/call",</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    "params":{</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">      "name":"weaviate-query-hybrid",</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">      "arguments":{</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">        "collection_name":"CodeChunks",</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">        "query":"how does FastAPI handle dependency injection",</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">        "limit":3</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">      }</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">    }</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">  }' | python3 -m json.tool</span><br></span></code></pre></div></div><p><strong>Success criteria:</strong> the response contains a <code>result</code> key with non-empty <code>content</code> and the matched chunks reference real files in <code>$CODE_DIR</code>. If the response is empty, ingest produced zero matchable chunks for this query — try a query you know is in the codebase.</p><h4 class="anchor anchorTargetStickyNavbar_Vzrq" id="done">Done<a href="#done" class="hash-link" aria-label="Direct link to Done" title="Direct link to Done" translate="no">​</a></h4><p>The agent now has hybrid search over the ingested codebase and docs. From the LLM client, queries that previously hallucinated will instead return citations from real files. To re-ingest after the codebase changes, delete the two collections (curl block above) and re-run <code>ingest.py</code>.</p></div></div></details>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="going-further">Going further<a href="#going-further" class="hash-link" aria-label="Direct link to Going further" title="Direct link to Going further" translate="no">​</a></h2>
<p>A few directions worth picking up after the basics work:</p>
<ul>
<li class="">
<p><strong>Multi-repo organizations</strong>: Switch the schema to multi-tenant and create one tenant per repo. The <code>weaviate-tenants-list</code> MCP tool gives the agent a way to discover them.</p>
</li>
<li class="">
<p><strong>Auth and RBAC</strong>: Weaviate's MCP server respects standard authentication. Three RBAC permissions (<code>read_mcp</code>, <code>create_mcp</code>, <code>update_mcp</code>) control who can do what. Hand out read-only MCP credentials to most users; reserve write access for trusted agents.</p>
</li>
<li class="">
<p><strong>Agent write-back</strong>: With write access on, the agent can persist its own findings (postmortem notes, cross-references it discovered, summaries of long-running work) back into Weaviate. The next session inherits them. This is what shifts Weaviate from a passive retrieval engine into long-term memory for the coding agent.</p>
</li>
<li class="">
<p><strong>Embedding choice</strong>: <code>text2vec-openai</code> is fine for most code. Voyage's <code>voyage-code-2</code> is better if you can swap it in. For fully local setups, point Weaviate at an Ollama-served embedding model.</p>
</li>
</ul>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="summary">Summary<a href="#summary" class="hash-link" aria-label="Direct link to Summary" title="Direct link to Summary" translate="no">​</a></h2>
<p>A coding assistant that doesn't know your code is a generic chatbot. The build is straightforward: index the codebase along syntactic boundaries, index the docs along heading boundaries, point your LLM client at the database via MCP, and let the agent retrieve only what it needs per query.</p>
<p>Weaviate simplifies this setup by running the MCP server inside the database. Hybrid search and multi-tenancy are enabled in the MCP service by default and writing directly to the database is one env var away. Spin it up, point Claude Code at it, and start asking questions about your actual code.</p>
<p>To go deeper:</p>
<ul>
<li class="">The <a class="" href="/blog/weaviate-1-37-release">Weaviate MCP server release notes</a></li>
<li class="">The <a href="https://github.com/weaviate/mcp-server-weaviate" target="_blank" rel="noopener noreferrer" class=""><code>weaviate/mcp-server-weaviate</code> GitHub repository</a></li>
<li class="">The <a href="https://modelcontextprotocol.io/docs/develop/build-server" target="_blank" rel="noopener noreferrer" class="">official MCP protocol docs</a></li>
<li class="">The <a class="" href="/blog/tokenization-text-analysis-weaviate">tokenization post</a> for the per-property tokenization rationale</li>
<li class="">Related blog posts: <a class="" href="/blog/what-is-agentic-rag">What is agentic RAG</a> and <a class="" href="/blog/hybrid-search-explained">Hybrid search explained</a></li>
</ul>
<!-- -->
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="ready-to-start-building">Ready to start building?<a href="#ready-to-start-building" class="hash-link" aria-label="Direct link to Ready to start building?" title="Direct link to Ready to start building?" translate="no">​</a></h2>
<p>Check out the <a href="https://docs.weaviate.io/weaviate/quickstart" target="_blank" rel="noopener noreferrer" class="">Quickstart tutorial</a>, or <a href="https://console.weaviate.cloud/?utm_source=blog&amp;utm_medium=website&amp;utm_campaign=blog_signup&amp;utm_content=coding-assistant-weaviate-mcp&amp;utm_term=ready-to-start-building" target="_blank" rel="noopener noreferrer">sign up for a free Weaviate Cloud account</a>.</p>
<!-- -->
]]></content:encoded>
            <category>agents</category>
            <category>engineering</category>
            <category>how-to</category>
        </item>
    </channel>
</rss>