docs: 1.39 Python client surfaces, corrections, and main reconciliation - #508
Merged
Conversation
…ries # Conflicts: # docs/agents/_includes/query_agent.mts # docs/agents/query/usage.md # docs/query-agent/_includes/code/query_agent.py
…bles ChunkSize has had no effect since its removal in core, but the page documented it as a working option with a default, minimum and maximum. Mark it deprecated and point to BACKUP_CHUNK_TARGET_SIZE. Document BACKUP_MIN_CHUNK_SIZE, BACKUP_CHUNK_TARGET_SIZE and BACKUP_SPLIT_FILE_SIZE, which were undocumented, including how their values are raised against each other. Document the location parameter for text2vec-google. No version markers: these all landed across several stable lines, so no single version is correct for every supported release.
- Add the one-shot SSB entry points to the batch import docs: data.ingest() (Python sync+async, TypeScript) and Batch.InsertMany (C#), alongside the streaming examples - Add an FAQ entry for the insert_many 'message larger than max' (RESOURCE_EXHAUSTED) failure with the verified client error and the ingest/SSB fix - State the GRPC_MAX_MESSAGE_SIZE default only in the env-vars table (row anchor added); other pages link to it; correct the stale 10MB value - Refactor manage-objects/import.mdx: remove the gRPC API and Python-specific sections, promote Error handling to its own section, rewrite Stream data from large files as tips, trim Asynchronous imports, and merge the four Specify sections under Customize imported objects with snippets moved to ingest/SSB (Go remains manual batching) - Rank SSB first on the Python client pages and best practices
- TypeScript: the server-side batching example now streams from a sync generator passed to data.ingest(), and a separate ServerSideIngestExample shows the in-memory array flavor (both executed against a live 1.38.0 with persistence checks) - Remove the Batch imports section from the Python client page - Remove the redundant lowercase anchor from the GRPC_MAX_MESSAGE_SIZE row (links use the APITable-generated anchor) - Add the data import best practices blog post to Further resources
The server-side batching, ingest, and error-handling sections mixed Python-specific method names into shared paragraphs. The shared prose is now language-neutral and each language tab carries its own wording, so a selected language reads as one coherent story. Error handling gains a per-language tab block; the Go tab stays generic because the Go example does not consume the batch response.
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Document server-side batching ingest and refactor the batch import page
Follow-up to #457, addressing review findings. Correctness: - structured_outputs.py: the citations snippet used Field() but only imported BaseModel, so the block raised NameError when copied. - Register structured_outputs.py/.mts in tests/test_agents.py; they were the only query-agent snippet files not covered by CI. - Bump weaviate-agents to >=1.7.0 (Python) and ^1.6.0 (TS); output_format and outputFormat do not exist in the pinned 1.6.0/1.5.0. Add zod as an explicit dependency - it was only resolving via hoisting of a transitive copy, though weaviate-agents declares it as a peer dep. Snippets: - Block-scope each TS example so they can all use `res`; the rendered docs were publishing res2/res3/res4/res5. - Use console.dir(..., { depth: null }) for the nested and citation examples, which console.log was abbreviating to `[Array]` - exactly the nested values those examples exist to show. - Move the zod import into the shared instantiation block, and call populateWeaviate/populate_weaviate as the other snippet files do. Docs: - Regenerate every example output from a single real run of each file. The previous outputs named "FictionalSoft", a party that appears in 0 of the 300 objects in the query-agent-financial-contracts dataset (the counterparty is OpenAI), so they were not reproducible. - Note that outputs are non-deterministic and will vary between runs. - State the minimum client versions and the Zod 4 requirement. - Correct the string-format row: formats constrain the shape the model generates but are not validated afterwards. A hostname-formatted field returned a 3606-character value, 14x the RFC 1123 limit. - Name ParsedAskModeResponse as the returned class in ask_mode.md. - Note that additionalProperties is optional, and why only the TS example carries it. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01CxMtvQPuFNT2ERqHx7C49z
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01CxMtvQPuFNT2ERqHx7C49z
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01CxMtvQPuFNT2ERqHx7C49z
The TS nested example had been trimmed from 8 entries to 6 with a reworded overall_summary, and the Python citations reasoning had its clauses reordered. Both now match the captured run output exactly. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01CxMtvQPuFNT2ERqHx7C49z
…-fixes [Agents] Structured outputs: review fixes
[Agents] Add structured output section
Add Docs for Follow-Up Queries in Suggest Queries Mode
The batch import page taught the iterable/generator form of the one-shot ingest call to TypeScript readers only, even though the Python client accepts any iterable too. Add the Python counterpart so both clients document the same capability. * New CI-executed snippet reads a JSONL file line by line and yields property dicts straight into the ingest call, so the file never has to fit in memory. Blank lines are skipped explicitly instead of relying on a null check that raises on them. * The snippet sits in the server-side batching tab, next to the streaming context, and links to the in-memory list section for the eager form. * "Stream data from large files" now names Python alongside TypeScript for the lazy-iterable option. Verified against Weaviate 1.38.0 with the CI-pinned client: 5 uuids returned, empty errors dict, all 5 titles persisted.
The page's only mention of the one-shot ingest call opened with "If your objects are already in an in-memory list", which is wrong by omission: the parameter is an iterable, so a generator works just as well. The page had no mention of generators anywhere. Rewrite that paragraph to cover both the eager and the lazy case, add a short generator snippet, and link to the batch import page for the version that reads a file line by line. Ingest is deliberately not added to the batch sizing table: it is a second entry point to server-side batching, not a fifth sizing mode. Snippet verified against Weaviate 1.38.0 with the CI-pinned client: 2 uuids returned, empty errors dict, both titles persisted.
Move every quickstart import step that has a one-shot server-side batching
equivalent to `data.ingest`, in Python and TypeScript.
Python: replaces `batch.fixed_size(...)` context managers with a single
`data.ingest(...)` call. Where vectors are supplied, objects are wrapped in
`DataObject` so the vector rides along.
TypeScript: replaces `data.insertMany(...)` with `data.ingest(...)`. The TS
client requires the `{ properties: ... }` object shape, so plain property
lists are mapped before the call.
Error handling: `data.ingest` has no context manager, so the old
`batch.failed_objects` / `batch.number_errors` guidance no longer applies.
The snippets now use the returned batch result. Python checks both
`has_errors` and `errors` because `has_errors` is not currently set on the
ingest path; TypeScript sets it correctly, so it checks `hasErrors`.
Go, Java and C# keep their current correct form: Go has no server-side
batching at all, and the Java and C# quickstarts already use the client-side
convenience method. Per-language asymmetry is acceptable, an invented API is
not.
The self-hosted quickstart gains a minimum server version note. Server-side
batching needs Weaviate 1.36 or later, and `data.ingest` has no client-side
version guard, so an older instance would fail with an opaque transport
error.
Snippets executed against Weaviate 1.38.0 with the CI-pinned clients.
- import.mdx: name `data.ingest()` inside the Python tab, and drop the Python-only method name from the shared "Stream data from large files" prose, linking to the server-side batching section instead. - notes-best-practices.mdx: promote the one-shot ingest material out of "Batch sizing" into its own "One-shot ingest" section, so it no longer splits "#### Usage" from the batching-method table it refers to. - notes-best-practices.mdx: document the `BatchObjectReturn` that `data.ingest()` returns under "Error handling", which previously covered only the batching-context API. - Snippet cleanups: use `collections.use()`, and trim two code comments that overclaimed or duplicated the surrounding prose.
- Import includes: name the API again in the Python tab, and give the TypeScript tab the error-handling prose it was missing. The shared "check the result" sentence now sits above the tabs, so it also covers the Go, Java and C# tabs. - Quickstart snippets: explain why the Python examples check `errors` directly, and label the TypeScript ingest call, matching the how-to. - cloud/quickstart.mdx, tutorials/quick-tour-of-weaviate.mdx: the batch tip claimed batching sends everything in a single request, which is no longer what the code beneath it does. Rewritten language-agnostically, and the doubled parenthesis and number disagreement are fixed. - quickstart/local.md: move the version caveat below the examples, switch it to the house `:::note Requirement: ...` pattern, and lead with the reassurance rather than the caveat.
Add a Python generator example for data.ingest
Gate the Python import examples on result.errors alone. The has_errors flag is not set on the ingest path, so the Python tab prose now names result.errors as the check to read. The TypeScript tab keeps hasErrors, which does fire on that client. Also drop the version-floor note from the local quickstart.
Fixes the 10 critical findings from a read-only audit of docs.weaviate.io (/weaviate, /deploy, /cloud), plus five High-tier findings in the same files and one stale include that contradicted a section fixed here. Every claim was checked against Weaviate core or the official client source. Wrong information a reader would act on: - Both quickstarts told the reader to sign up for Cohere while every client snippet required an OpenAI key. Prose and the curl tabs now say OpenAI, matching the CI-executed snippets; Java and C# collection config switched to OpenAI to match. - google/generative marked gemini-2.5-flash as the default, but omitting the model makes the server fall back to a legacy PaLM model that the same page lists as deprecated. Marker removed, with a caution to set the model. - google/embeddings: the Gemini example failed server-side validation. Python passed a keyword the client rejects, Go named the wrong module, and the AI Studio examples omitted the Gemini endpoint, so collection creation failed with "projectId cannot be empty". - anthropic/generative had a default and model list frozen at July 2024. Default corrected; the hand-maintained list replaced with a link to the provider's model-names page, since the module has no allowlist. - search/similarity MMR examples used a parameter and factory that had both been renamed, so the snippets raised on use. All five call sites and the surrounding prose corrected. - OPERATIONAL_MODE documented values the parser does not accept, and an unrecognized value silently falls back to full read-write. Values corrected and the silent fallback documented. - The cluster-consensus troubleshooting answer was a verbatim copy of the unrelated async-replication answer. Rewritten around cluster membership and Raft. Corrected the case of ASYNC_REPLICATION_DISABLED. Snippets that could not run as printed: - typescript/notes-best-practices had pasted GitHub review UI text inside a JS block, making it a SyntaxError on copy-paste, plus invalid generic syntax. - read-all-objects used Go markers that appear twice in the source, so the snippet component spliced two regions together and leaked raw import lines into non-compiling Go. Unique markers added. Two further Go tabs referenced markers that do not exist and rendered as empty code boxes; those tabs are removed rather than left blank. - Removed a preview bullet claiming Python client support was unreleased. It has shipped, and that include renders into the MMR section corrected here. Enables tests/test_python.py::test_search_mmr. It was skipped on the stale grounds that MMR support was not in a released client; support has shipped, and the snippet runs green against a live instance using self-provided vectors, so it needs no provider credentials. The test now covers the corrected MMR examples in CI.
…steps Java and C# were the last quickstart tabs still using client-side batching while the docs recommend server-side batching as the default. Java: `collection.data.insertMany(...)` becomes `collection.batch.start()`, which returns a `BatchContext`. The context is closed with try-with-resources so `close()` flushes the remaining objects and waits for the results, and `batch.numberOfErrors()` is read after the block, once the tally is complete. C#: `collection.Data.InsertMany(...)` becomes `collection.Batch.InsertMany(...)`. Both return a `BatchInsertResponse`, so the error handling keeps its shape and gains a per-entry loop. The `HasErrors` check moves inside the `END Import` marker so the docs tab renders it, matching the Java tab. Go keeps client-side batching because the Go client has no server-side batching API. The README examples are left alone. The shared line above the tabs now says a result reports whether any objects failed rather than which ones, because the Java tally is a count. The Java and C# tabs each gain a sentence naming their own result type.
Addresses review feedback on this pull request. Weaviate matches module config keys by exact string, a plain map lookup with no case normalization and a silent fallback to the default on a miss. The snake_case keys these examples used were therefore ignored by the server: two of the three blocks failed collection creation with "projectId cannot be empty", and the model each example set was never applied. The accepted keys are apiEndpoint, projectId and modelId, which is also what this page's own parameter reference documents, so the snippets contradicted the prose beside them. Also corrects a "Vertex AU" typo, and rewrites a troubleshooting sentence that read "Check your settings to check ..." and referred to "peers checks".
The shared line above the tabs claimed every import "returns a result". That is false for Java: `batch.start()` hands back the `BatchContext` before any object is added, the try-with-resources block returns nothing, and the tally is read off a handle the reader already holds. It also primes the mental model that causes the premature read, because the only candidate for "the result the import gave me" is the object returned before the import ran. The line now says imports report whether any objects failed, without claiming a return value. The C# sentence said each entry carries "the `Error` that failed it", but `Error` is nullable and null on success, as the sample two lines below already shows with `.Where(o => o.Error is not null)`. It also left `Index` unnamed while the code prints it and the Python and TS tabs explain positional keying. The sentence now names `HasErrors`, `Errors`, `Objects`, `Index`, and `Error`, and says only failed entries carry an `Error`. The Java timing moves out of a trailing adverb into its own sentence, since reading `numberOfErrors()` before the batch closes is the one thing a reader can silently get wrong. In the C# samples, the comment above the failure loop now names `Index` and matches the Python and TS phrasing instead of saying "in the order they were sent", and the success count uses `insertResponse.Count` like the four sibling quickstart files rather than `Objects.Count()`.
docs(deploy,configuration): fix commands that fail on paste, wrong parameter names, and missing reference
docs(model-providers): fix structure, model lists, and a wrong published token limit
docs(model-providers): copy-editing across provider pages
docs(tutorials): fix invalid JSON, a duplicate card icon, and em dashes
docs(modules,connections): fix Go tab rendering, a stale image tag, and unreachable pages
…ector config The note on the `object` data type claimed absolutely that `object` and `object[]` properties are not vectorized. That conflicts with config-refs/indexing/vector-index.mdx, which documents that non-text types, including `object`, are vectorized when explicitly listed as source properties. Core confirms the docs page was wrong. In usecases/modulecomponents/vectorizer/object_texts.go the default switch handles only `string` and `[]string`; everything else falls through to a no-op. A second switch, guarded by `hasSourceProperties`, adds `map[string]any` and `[]map[string]any`, which are passed through `marshalValue` (json.Marshal, with a fmt.Sprintf fallback) and inserted into the vectorized corpus. So a listed object property is vectorized as its JSON representation. The sentence also conflated two independent mechanisms behind a single clause: vectorization and inverted-index storage. The inverted-index half was correct. Split them so each can be stated accurately, and align the wording and vocabulary with vector-index.mdx, which owns this topic. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01DzkwXqkMC6agu8oGNswh2b
…-location docs: correct deprecated ChunkSize and document backup chunking variables
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
docs(cloud): remove dead imports, add the missing default-index row, fix typos
The "Python clients" section stated when embedded support landed in the Python v3 client (v3.15.4 on Linux, v3.21.0 on macOS). That client has been removed, so the fact describes software that no longer exists, and the client version numbers violate the house rule against client library versions in prose. Replace it with the current story: embedded support ships inside the Python client, with no separate package, which is the counterpart to the TypeScript section immediately below where the embedded client IS a separate package. The Weaviate server requirement (v1.23.7 or later) is kept. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01DzkwXqkMC6agu8oGNswh2b
docs: assorted one-line defects, plus a stale gRPC section and a silently wrong tab
docs: house-style sweep across reference and concepts pages
# Conflicts: # docs/cloud/embeddings/quickstart.mdx # docs/deploy/configuration/backups.md # docs/deploy/configuration/env-vars/index.md # docs/deploy/installation-guides/embedded.md # docs/weaviate/client-libraries/go.md # docs/weaviate/concepts/interface.md # docs/weaviate/model-providers/_includes/provider.vectorizer.py # docs/weaviate/model-providers/cohere/embeddings-multimodal.md # docs/weaviate/model-providers/google/embeddings-multimodal.md # docs/weaviate/model-providers/voyageai/embeddings.md # docs/weaviate/starter-guides/custom-vectors.mdx
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
docs: low-severity fixes from the docs deep review
A verification pass over all 205 deep-review findings found these five still present in main. Each was parked behind a blocker that has since cleared. Two Helm examples that do not work when pasted. The RBAC values block did not parse at all; PyYAML rejected it with "mapping values are not allowed here" because rbac: sat as a sibling of authorization: and root_users: carried a stray indent. The CLUSTER_HOSTNAME example used list syntax where the chart ranges over a map, so it parsed as a one-element list containing a map. Both corrected against the chart itself, and both parse results checked before and after rather than eyeballed. The generative starter guide documented two wrong model defaults and six JSON keys that do not exist. The *Property names it used are Go variable identifiers, not wire keys, and one parameter it showed has been removed from the module entirely. Rather than correct numbers that will rot again, the legacy raw-JSON moduleConfig examples are replaced with the current Configure.Generative pattern and the defaults now point at the model provider pages. The returned collection definition on the managing-collections guide was several years stale: it showed the pre-named-vector flat shape and invented description fields the snippet never sets. It is now a real response captured from a running instance, with only the collection name changed. The Java tab of the quickstart RAG example rendered "// Coming soon" while four other languages rendered working code. It now has a real test.
docs: fix five review findings that were never dispatched
The OpenAI embeddings page documented `baseURL` but not the `endpoint` parameter that sets the path appended to it. The generative page listed the `X-OpenAI-Baseurl` header with no explanation of the path at all, and appends a different one. - embeddings: document the `endpoint` parameter and how the request URL is composed, and cross-link the two sections - generative: add the equivalent note, covering the legacy `/v1/completions` path and the absence of an `endpoint` override - both: note that the Azure integration builds its own path - drop the third-party gateway named in the old proxy example
…ction docs(model-providers): document how OpenAI request URLs are built
Add docs for `effort` in Search Mode
Reconciles 111 commits of main into v1-39/main, which had drifted far enough that PR #479 could no longer merge. Only _includes/feature-notes/boost.mdx conflicted textually; the other 12 files GitHub reported auto-merged. All 13 were checked against both parents anyway. boost.mdx is the one place both sides could not be kept: main restyled the Preview caution's title on a line the 1.39 work deletes outright, because Boost is GA in 1.39. Took the 1.39 side.
Documents the user-facing surfaces that weaviate-client 4.23.0 adds for Weaviate 1.39, and corrects several published statements that the 1.38 patch line had already made false. Corrections: - similarity.md said diversity selection was 'Not supported' for hybrid search. That has been false since v1.38.6. Multi-vector remains correctly unsupported. - bm25.md and search-operators.md published exhaustive operator lists that omitted AndCross. - replica-movement.mdx and consistency.md published exhaustive replication-state lists that omitted INTEGRATING (added in v1.38.0). - The MMR feature note still carried a preview label and a multi-node caveat that no longer applies, MMR now being a single coordinator pass. - aws/embeddings.md described 'service' as required while also giving it a default. It is optional; core defaults it to bedrock. - A Bedrock snippet used titan-embed-text-v2:0 without the amazon. prefix. Core dispatches on that prefix, so the collection was created and then failed later at import time. New coverage: - Cross-property AND (and_cross), Python and GraphQL, with the tokenization and analyzer constraint that makes it fail. - Diversity selection on hybrid search, including the pagination contract: offset advances by the query limit, not the page size, and nothing validates it. - list_backups() and the list-side incremental_base_backup_id, which is distinct from the create-side parameter of the same name. - dimensions on text2vec-aws, and a location example for text2vec-google. Version markers cite the release a capability actually became available in, not 1.39: v1.37.3 and v1.38.6 for MMR, v1.38.6 for hybrid diversity, v1.38.8 for and_cross, v1.38.0 for INTEGRATING. The client pin moves to 4.23.0 and the test servers to 1.39.0. 4.23.0 is not on PyPI yet, so uv.lock cannot be regenerated and the Python CI lanes will fail at dependency install until it publishes.
![orca-security-eu[bot]](https://avatars.githubusercontent.com/in/276244?s=60&v=4){kind=small}
There was a problem hiding this comment.
Orca Security Scan Summary
| Status | Check | Issues by priority | |
|---|---|---|---|
 Passed |
Secrets |  0  0  0  0 |
View in Orca |
This was referenced Aug 12, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Two commits: the merge of
maininto the release branch, then the 1.39 docs work. Merging this unblocks #479, which is conflicting becausemainran 111 commits ahead ofv1-39/main.Python CI will fail, expected
pyproject.tomlpinsweaviate-client==4.23.0, which is not on PyPI yet, souv synccannot resolve it and the Python lanes die at dependency install. Clears itself when 4.23.0 publishes, along withuv.lockand the release-history link.Corrections
Four pages published statements the 1.38 patch line had already made false:
search/similarity.mdsaid diversity selection was "Not supported" for hybrid. It shipped in v1.38.6. Multi-vector is still correctly unsupported.search/bm25.mdandapi/graphql/search-operators.mdlisted onlyandandor.AndCrossshipped in v1.38.8, as a GraphQL enum too.replica-movement.mdxandconsistency.mdlisted six replication states, omittingINTEGRATING(v1.38.0).aws/embeddings.mdcalledservicerequired while also giving it a default. It is optional.Plus two snippet fixes: the MMR note dropped a stale preview label and a multi-node caveat that no longer applies, and a Bedrock example was missing the
amazon.prefix, which fails at import rather than at collection creation.New for client 4.23.0
BM25Operator.and_cross()(Python and GraphQL),diversity_selectionon hybrid,list_backups()and the list-sideincremental_base_backup_id,dimensionsontext2vec-aws, alocationexample fortext2vec-google,has_errorsondata.ingest(), and the 1.39 compatibility row and version cards.Version markers cite where each capability actually landed, not 1.39.
Known, not fixed here
provider.vectorizer.tsSageMaker block setsmodel:with noendpoint:; core rejects it at collection creation. Needs a placeholder decision.orandandtabs onbm25.mdrender empty code blocks, missing// STARTmarkers. Pre-existing._includes/feature-notes/v137-preview.mdxis now a misleading filename.