From 307abb00cc1ba6cc95de0b9dfd4d6d2d0eb11ffb Mon Sep 17 00:00:00 2001 From: Ivan Despot <66276597+g-despot@users.noreply.github.com> Date: Wed, 29 Jul 2026 13:46:13 +0200 Subject: [PATCH 1/6] docs(quickstart): use the shorter ingest form for the import step 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. --- _includes/code/llms-txt/python/quickstart.py | 4 +-- .../code/llms-txt/typescript/quickstart.ts | 2 +- .../python/local.quickstart.import_objects.py | 35 +++++++++---------- .../code/python/quickstart.import_objects.py | 35 +++++++++---------- .../quickstart.short.create_collection.py | 4 +-- ....short.import_vectors.create_collection.py | 8 +++-- ...uickstart.short.local.create_collection.py | 4 +-- ....local.import_vectors.create_collection.py | 8 +++-- .../local.quickstart.import_objects.mdx | 2 +- .../quickstart/quickstart.import_objects.mdx | 2 +- .../local.quickstart.import_objects.ts | 20 +++++++---- .../typescript/quickstart.import_objects.ts | 20 +++++++---- .../quickstart.short.create_collection.ts | 4 ++- ....short.import_vectors.create_collection.ts | 2 +- ...uickstart.short.local.create_collection.ts | 4 ++- ....local.import_vectors.create_collection.ts | 2 +- docs/weaviate/quickstart/local.md | 4 +++ 17 files changed, 90 insertions(+), 70 deletions(-) diff --git a/_includes/code/llms-txt/python/quickstart.py b/_includes/code/llms-txt/python/quickstart.py index 30ad432ff..7f46cb2c1 100644 --- a/_includes/code/llms-txt/python/quickstart.py +++ b/_includes/code/llms-txt/python/quickstart.py @@ -46,9 +46,7 @@ movies = client.collections.use("Movie__QuickstartPy") # Import objects - with movies.batch.fixed_size(batch_size=200) as batch: - for obj in data_objects: - batch.add_object(properties=obj) + movies.data.ingest(data_objects) print(f"Imported & vectorized {len(data_objects)} objects into the Movie collection") diff --git a/_includes/code/llms-txt/typescript/quickstart.ts b/_includes/code/llms-txt/typescript/quickstart.ts index a83e17a1e..3270ee824 100644 --- a/_includes/code/llms-txt/typescript/quickstart.ts +++ b/_includes/code/llms-txt/typescript/quickstart.ts @@ -36,7 +36,7 @@ if (!(await client.collections.exists('Movie__QuickstartTs'))) { const movies = client.collections.use('Movie__QuickstartTs'); // Import objects -await movies.data.insertMany(dataObjects); +await movies.data.ingest(dataObjects.map((properties) => ({ properties }))); console.log(`Imported & vectorized ${dataObjects.length} objects into the Movie collection`); diff --git a/_includes/code/python/local.quickstart.import_objects.py b/_includes/code/python/local.quickstart.import_objects.py index 9f9c3d7b4..d215211cf 100644 --- a/_includes/code/python/local.quickstart.import_objects.py +++ b/_includes/code/python/local.quickstart.import_objects.py @@ -9,27 +9,26 @@ ) data = json.loads(resp.text) -# highlight-start questions = client.collections.use("Question") -with questions.batch.fixed_size(batch_size=200) as batch: - for d in data: - batch.add_object( - { - "answer": d["Answer"], - "question": d["Question"], - "category": d["Category"], - } - ) - # highlight-end - if batch.number_errors > 10: - print("Batch import stopped due to excessive errors.") - break +# highlight-start +result = questions.data.ingest( + [ + { + "answer": d["Answer"], + "question": d["Question"], + "category": d["Category"], + } + for d in data + ] +) +# highlight-end -failed_objects = questions.batch.failed_objects -if failed_objects: - print(f"Number of failed imports: {len(failed_objects)}") - print(f"First failed object: {failed_objects[0]}") +if result.has_errors or result.errors: + print(f"Number of failed imports: {len(result.errors)}") + # `errors` is keyed by the position of the object in the input + for index, error in result.errors.items(): + print(f"Failed object at index {index}: {error.message}") client.close() # Free up resources # END Import diff --git a/_includes/code/python/quickstart.import_objects.py b/_includes/code/python/quickstart.import_objects.py index fa89fdf71..f72be5856 100644 --- a/_includes/code/python/quickstart.import_objects.py +++ b/_includes/code/python/quickstart.import_objects.py @@ -17,27 +17,26 @@ ) data = json.loads(resp.text) -# highlight-start questions = client.collections.use("Question") -with questions.batch.fixed_size(batch_size=200) as batch: - for d in data: - batch.add_object( - { - "answer": d["Answer"], - "question": d["Question"], - "category": d["Category"], - } - ) - # highlight-end - if batch.number_errors > 10: - print("Batch import stopped due to excessive errors.") - break +# highlight-start +result = questions.data.ingest( + [ + { + "answer": d["Answer"], + "question": d["Question"], + "category": d["Category"], + } + for d in data + ] +) +# highlight-end -failed_objects = questions.batch.failed_objects -if failed_objects: - print(f"Number of failed imports: {len(failed_objects)}") - print(f"First failed object: {failed_objects[0]}") +if result.has_errors or result.errors: + print(f"Number of failed imports: {len(result.errors)}") + # `errors` is keyed by the position of the object in the input + for index, error in result.errors.items(): + print(f"Failed object at index {index}: {error.message}") client.close() # Free up resources # END Import diff --git a/_includes/code/python/quickstart.short.create_collection.py b/_includes/code/python/quickstart.short.create_collection.py index a4685294d..62becb3a9 100644 --- a/_includes/code/python/quickstart.short.create_collection.py +++ b/_includes/code/python/quickstart.short.create_collection.py @@ -42,9 +42,7 @@ # START CreateCollection movies = client.collections.use("Movie") - with movies.batch.fixed_size(batch_size=200) as batch: - for obj in data_objects: - batch.add_object(properties=obj) + movies.data.ingest(data_objects) print(f"Imported & vectorized {len(movies)} objects into the Movie collection") # END CreateCollection diff --git a/_includes/code/python/quickstart.short.import_vectors.create_collection.py b/_includes/code/python/quickstart.short.import_vectors.create_collection.py index 2211e39ae..76a15f1b8 100644 --- a/_includes/code/python/quickstart.short.import_vectors.create_collection.py +++ b/_includes/code/python/quickstart.short.import_vectors.create_collection.py @@ -1,6 +1,7 @@ # START CreateCollection import weaviate from weaviate.classes.config import Configure +from weaviate.classes.data import DataObject import os # Best practice: store your credentials in environment variables @@ -46,9 +47,10 @@ # Insert the objects with vectors movies = client.collections.get("Movie") - with movies.batch.fixed_size(batch_size=200) as batch: - for obj in data_objects: - batch.add_object(properties=obj["properties"], vector=obj["vector"]) + movies.data.ingest( + DataObject(properties=obj["properties"], vector=obj["vector"]) + for obj in data_objects + ) print( f"Imported {len(data_objects)} objects with vectors into the Movie collection" diff --git a/_includes/code/python/quickstart.short.local.create_collection.py b/_includes/code/python/quickstart.short.local.create_collection.py index 5d8cdfc56..ff8ce55a0 100644 --- a/_includes/code/python/quickstart.short.local.create_collection.py +++ b/_includes/code/python/quickstart.short.local.create_collection.py @@ -36,9 +36,7 @@ # START CreateCollection movies = client.collections.use("Movie") - with movies.batch.fixed_size(batch_size=200) as batch: - for obj in data_objects: - batch.add_object(properties=obj) + movies.data.ingest(data_objects) print(f"Imported & vectorized {len(movies)} objects into the Movie collection") # END CreateCollection diff --git a/_includes/code/python/quickstart.short.local.import_vectors.create_collection.py b/_includes/code/python/quickstart.short.local.import_vectors.create_collection.py index 208b7a31c..f5a874884 100644 --- a/_includes/code/python/quickstart.short.local.import_vectors.create_collection.py +++ b/_includes/code/python/quickstart.short.local.import_vectors.create_collection.py @@ -1,6 +1,7 @@ # START CreateCollection import weaviate from weaviate.classes.config import Configure +from weaviate.classes.data import DataObject # Step 1.1: Connect to your local Weaviate instance with weaviate.connect_to_local() as client: @@ -38,9 +39,10 @@ # Insert the objects with vectors movies = client.collections.get("Movie") - with movies.batch.fixed_size(batch_size=200) as batch: - for obj in data_objects: - batch.add_object(properties=obj["properties"], vector=obj["vector"]) + movies.data.ingest( + DataObject(properties=obj["properties"], vector=obj["vector"]) + for obj in data_objects + ) print( f"Imported {len(data_objects)} objects with vectors into the Movie collection" diff --git a/_includes/code/quickstart/local.quickstart.import_objects.mdx b/_includes/code/quickstart/local.quickstart.import_objects.mdx index 705df5b35..52d0bf92c 100644 --- a/_includes/code/quickstart/local.quickstart.import_objects.mdx +++ b/_includes/code/quickstart/local.quickstart.import_objects.mdx @@ -19,7 +19,7 @@ import CSharpCode from "!!raw-loader!/_includes/code/csharp/QuickstartLocalTest. title="quickstart_import.py" /> -During a batch import, any failed objects can be obtained through `batch.failed_objects`. Additionally, a running count of failed objects is maintained and can be accessed through `batch.number_errors` within the context manager. This counter can be used to stop the import process in order to investigate the failed objects or references. Find out more about error handling on the Python client [reference page](/weaviate/client-libraries/python/notes-best-practices#error-handling). +The import returns a result object that reports whether anything failed, along with an entry for each failed object keyed by its position in the input. Check it after every import so that problems such as malformed data or a misconfigured model provider do not go unnoticed. Find out more about error handling on the Python client [reference page](/weaviate/client-libraries/python/notes-best-practices#error-handling). diff --git a/_includes/code/quickstart/quickstart.import_objects.mdx b/_includes/code/quickstart/quickstart.import_objects.mdx index 35ef8a581..93c94c8e7 100644 --- a/_includes/code/quickstart/quickstart.import_objects.mdx +++ b/_includes/code/quickstart/quickstart.import_objects.mdx @@ -20,7 +20,7 @@ import CSharpCode from "!!raw-loader!/_includes/code/csharp/QuickstartTest.cs"; /> -During a batch import, any failed objects can be obtained through `batch.failed_objects`. Additionally, a running count of failed objects is maintained and can be accessed through `batch.number_errors` within the context manager. This counter can be used to stop the import process in order to investigate the failed objects or references. Find out more about error handling on the Python client [reference page](/weaviate/client-libraries/python/notes-best-practices#error-handling). +The import returns a result object that reports whether anything failed, along with an entry for each failed object keyed by its position in the input. Check it after every import so that problems such as malformed data or a misconfigured model provider do not go unnoticed. Find out more about error handling on the Python client [reference page](/weaviate/client-libraries/python/notes-best-practices#error-handling). diff --git a/_includes/code/typescript/local.quickstart.import_objects.ts b/_includes/code/typescript/local.quickstart.import_objects.ts index ffe894279..736b017ee 100644 --- a/_includes/code/typescript/local.quickstart.import_objects.ts +++ b/_includes/code/typescript/local.quickstart.import_objects.ts @@ -11,18 +11,26 @@ async function getJsonData() { return file.json(); } -// highlight-start -// Note: The TS client does not have a `batch` method yet -// We use `insertMany` instead, which sends all of the data in one request async function importQuestions() { const questions = client.collections.use('Question'); const data = await getJsonData(); - const result = await questions.data.insertMany(data); - console.log('Insertion response: ', result); + + // highlight-start + const result = await questions.data.ingest( + data.map((properties) => ({ properties })) + ); + // highlight-end + + if (result.hasErrors) { + console.log(`Number of failed imports: ${Object.keys(result.errors).length}`); + // `errors` is keyed by the position of the object in the input + for (const [index, error] of Object.entries(result.errors)) { + console.log(`Failed object at index ${index}: ${error.message}`); + } + } } await importQuestions(); -// highlight-end client.close(); // Close the client connection // END Import diff --git a/_includes/code/typescript/quickstart.import_objects.ts b/_includes/code/typescript/quickstart.import_objects.ts index b04257fd7..47635eca9 100644 --- a/_includes/code/typescript/quickstart.import_objects.ts +++ b/_includes/code/typescript/quickstart.import_objects.ts @@ -20,18 +20,26 @@ async function getJsonData() { return file.json(); } -// highlight-start -// Note: The TS client does not have a `batch` method yet -// We use `insertMany` instead, which sends all of the data in one request async function importQuestions() { const questions = client.collections.use('Question'); const data = await getJsonData(); - const result = await questions.data.insertMany(data); - console.log('Insertion response: ', result); + + // highlight-start + const result = await questions.data.ingest( + data.map((properties) => ({ properties })) + ); + // highlight-end + + if (result.hasErrors) { + console.log(`Number of failed imports: ${Object.keys(result.errors).length}`); + // `errors` is keyed by the position of the object in the input + for (const [index, error] of Object.entries(result.errors)) { + console.log(`Failed object at index ${index}: ${error.message}`); + } + } } await importQuestions(); -// highlight-end client.close(); // Close the client connection // END Import diff --git a/_includes/code/typescript/quickstart.short.create_collection.ts b/_includes/code/typescript/quickstart.short.create_collection.ts index 3c7e5fb88..167ff7734 100644 --- a/_includes/code/typescript/quickstart.short.create_collection.ts +++ b/_includes/code/typescript/quickstart.short.create_collection.ts @@ -41,7 +41,9 @@ const dataObjects = [ // START CreateCollection const movieCollection = client.collections.get('Movie'); -const response = await movieCollection.data.insertMany(dataObjects); +await movieCollection.data.ingest( + dataObjects.map((properties) => ({ properties })) +); console.log(`Imported & vectorized ${dataObjects.length} objects into the Movie collection`); diff --git a/_includes/code/typescript/quickstart.short.import_vectors.create_collection.ts b/_includes/code/typescript/quickstart.short.import_vectors.create_collection.ts index a8f0cced0..82e4a8aae 100644 --- a/_includes/code/typescript/quickstart.short.import_vectors.create_collection.ts +++ b/_includes/code/typescript/quickstart.short.import_vectors.create_collection.ts @@ -51,7 +51,7 @@ const dataObjects = [ // START CreateCollection // Insert the objects with vectors const movieCollection = client.collections.get('Movie'); -const response = await movieCollection.data.insertMany(dataObjects); +await movieCollection.data.ingest(dataObjects); console.log(`Imported ${dataObjects.length} objects with vectors into the Movie collection`); diff --git a/_includes/code/typescript/quickstart.short.local.create_collection.ts b/_includes/code/typescript/quickstart.short.local.create_collection.ts index dabb209d9..239cae8fa 100644 --- a/_includes/code/typescript/quickstart.short.local.create_collection.ts +++ b/_includes/code/typescript/quickstart.short.local.create_collection.ts @@ -35,7 +35,9 @@ const dataObjects = [ // START CreateCollection const movieCollection = client.collections.get('Movie'); -const response = await movieCollection.data.insertMany(dataObjects); +await movieCollection.data.ingest( + dataObjects.map((properties) => ({ properties })) +); console.log(`Imported & vectorized ${dataObjects.length} objects into the Movie collection`); diff --git a/_includes/code/typescript/quickstart.short.local.import_vectors.create_collection.ts b/_includes/code/typescript/quickstart.short.local.import_vectors.create_collection.ts index 871ffe26c..6c667bcba 100644 --- a/_includes/code/typescript/quickstart.short.local.import_vectors.create_collection.ts +++ b/_includes/code/typescript/quickstart.short.local.import_vectors.create_collection.ts @@ -36,7 +36,7 @@ const dataObjects = [ // Insert the objects with vectors const movieCollection = client.collections.get('Movie'); -const response = await movieCollection.data.insertMany(dataObjects); +await movieCollection.data.ingest(dataObjects); console.log(`Imported ${dataObjects.length} objects with vectors into the Movie collection`); diff --git a/docs/weaviate/quickstart/local.md b/docs/weaviate/quickstart/local.md index ea5cd21e1..546e65442 100644 --- a/docs/weaviate/quickstart/local.md +++ b/docs/weaviate/quickstart/local.md @@ -126,6 +126,10 @@ import CodeClientInstall from "/_includes/code/quickstart/clients.install.new.md ## Step 1: Create a collection & import data {#create-a-collection} +:::info Minimum Weaviate version +The Python and JavaScript/TypeScript examples below import data with [server-side batching](../manage-objects/import.mdx#server-side-batching), which requires Weaviate `v1.36` or later. The Docker Compose file above runs a current release, so this is only a concern if you point the examples at an older instance. +::: + There are two paths you can choose from when importing data: From de248fb9ba28a1342eb88bfd16d89fdbfa72fbb5 Mon Sep 17 00:00:00 2001 From: g-despot Date: Wed, 29 Jul 2026 14:11:53 +0200 Subject: [PATCH 2/6] docs(quickstart): apply editor review to the ingest migration - 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. --- _includes/code/python/local.quickstart.import_objects.py | 1 + _includes/code/python/quickstart.import_objects.py | 1 + .../code/quickstart/local.quickstart.import_objects.mdx | 6 +++++- _includes/code/quickstart/quickstart.import_objects.mdx | 6 +++++- .../code/typescript/local.quickstart.import_objects.ts | 1 + _includes/code/typescript/quickstart.import_objects.ts | 1 + docs/cloud/quickstart.mdx | 4 ++-- docs/weaviate/quickstart/local.md | 8 ++++---- docs/weaviate/tutorials/quick-tour-of-weaviate.mdx | 4 ++-- 9 files changed, 22 insertions(+), 10 deletions(-) diff --git a/_includes/code/python/local.quickstart.import_objects.py b/_includes/code/python/local.quickstart.import_objects.py index d215211cf..29e543ddd 100644 --- a/_includes/code/python/local.quickstart.import_objects.py +++ b/_includes/code/python/local.quickstart.import_objects.py @@ -24,6 +24,7 @@ ) # highlight-end +# Also check `errors` directly; it is populated for every failed object if result.has_errors or result.errors: print(f"Number of failed imports: {len(result.errors)}") # `errors` is keyed by the position of the object in the input diff --git a/_includes/code/python/quickstart.import_objects.py b/_includes/code/python/quickstart.import_objects.py index f72be5856..a73ba124d 100644 --- a/_includes/code/python/quickstart.import_objects.py +++ b/_includes/code/python/quickstart.import_objects.py @@ -32,6 +32,7 @@ ) # highlight-end +# Also check `errors` directly; it is populated for every failed object if result.has_errors or result.errors: print(f"Number of failed imports: {len(result.errors)}") # `errors` is keyed by the position of the object in the input diff --git a/_includes/code/quickstart/local.quickstart.import_objects.mdx b/_includes/code/quickstart/local.quickstart.import_objects.mdx index 52d0bf92c..ab4b5c60c 100644 --- a/_includes/code/quickstart/local.quickstart.import_objects.mdx +++ b/_includes/code/quickstart/local.quickstart.import_objects.mdx @@ -8,6 +8,8 @@ import JavaV6Code from "!!raw-loader!/_includes/code/java-v6/src/test/java/Quick import CSharpCode from "!!raw-loader!/_includes/code/csharp/QuickstartLocalTest.cs"; +Every import returns a result that reports which objects failed, if any. Check it in your own code to catch problems such as malformed data or a misconfigured model provider. + @@ -19,7 +21,7 @@ import CSharpCode from "!!raw-loader!/_includes/code/csharp/QuickstartLocalTest. title="quickstart_import.py" /> -The import returns a result object that reports whether anything failed, along with an entry for each failed object keyed by its position in the input. Check it after every import so that problems such as malformed data or a misconfigured model provider do not go unnoticed. Find out more about error handling on the Python client [reference page](/weaviate/client-libraries/python/notes-best-practices#error-handling). +`data.ingest()` returns a `BatchObjectReturn`. Read `result.has_errors` for a quick check, and `result.errors` for one entry per failed object, keyed by its position in the input. For more, see [error handling in the Python client reference](/weaviate/client-libraries/python/notes-best-practices#error-handling). @@ -33,6 +35,8 @@ The import returns a result object that reports whether anything failed, along w title="quickstart_import.ts" /> +`data.ingest()` returns a result object. Read `result.hasErrors` for a quick check, and `result.errors` for one entry per failed object, keyed by its position in the input. + diff --git a/_includes/code/quickstart/quickstart.import_objects.mdx b/_includes/code/quickstart/quickstart.import_objects.mdx index 93c94c8e7..9104791f2 100644 --- a/_includes/code/quickstart/quickstart.import_objects.mdx +++ b/_includes/code/quickstart/quickstart.import_objects.mdx @@ -8,6 +8,8 @@ import JavaV6Code from "!!raw-loader!/_includes/code/java-v6/src/test/java/Quick import CSharpCode from "!!raw-loader!/_includes/code/csharp/QuickstartTest.cs"; +Every import returns a result that reports which objects failed, if any. Check it in your own code to catch problems such as malformed data or a misconfigured model provider. + @@ -20,7 +22,7 @@ import CSharpCode from "!!raw-loader!/_includes/code/csharp/QuickstartTest.cs"; /> -The import returns a result object that reports whether anything failed, along with an entry for each failed object keyed by its position in the input. Check it after every import so that problems such as malformed data or a misconfigured model provider do not go unnoticed. Find out more about error handling on the Python client [reference page](/weaviate/client-libraries/python/notes-best-practices#error-handling). +`data.ingest()` returns a `BatchObjectReturn`. Read `result.has_errors` for a quick check, and `result.errors` for one entry per failed object, keyed by its position in the input. For more, see [error handling in the Python client reference](/weaviate/client-libraries/python/notes-best-practices#error-handling). @@ -34,6 +36,8 @@ The import returns a result object that reports whether anything failed, along w title="quickstart_import.ts" /> +`data.ingest()` returns a result object. Read `result.hasErrors` for a quick check, and `result.errors` for one entry per failed object, keyed by its position in the input. + diff --git a/_includes/code/typescript/local.quickstart.import_objects.ts b/_includes/code/typescript/local.quickstart.import_objects.ts index 736b017ee..dfa4a0861 100644 --- a/_includes/code/typescript/local.quickstart.import_objects.ts +++ b/_includes/code/typescript/local.quickstart.import_objects.ts @@ -16,6 +16,7 @@ async function importQuestions() { const data = await getJsonData(); // highlight-start + // `ingest` imports the list using server-side batching const result = await questions.data.ingest( data.map((properties) => ({ properties })) ); diff --git a/_includes/code/typescript/quickstart.import_objects.ts b/_includes/code/typescript/quickstart.import_objects.ts index 47635eca9..43aebb365 100644 --- a/_includes/code/typescript/quickstart.import_objects.ts +++ b/_includes/code/typescript/quickstart.import_objects.ts @@ -25,6 +25,7 @@ async function importQuestions() { const data = await getJsonData(); // highlight-start + // `ingest` imports the list using server-side batching const result = await questions.data.ingest( data.map((properties) => ({ properties })) ); diff --git a/docs/cloud/quickstart.mdx b/docs/cloud/quickstart.mdx index 7039863d7..fd581c138 100644 --- a/docs/cloud/quickstart.mdx +++ b/docs/cloud/quickstart.mdx @@ -221,11 +221,11 @@ We can now add data to our collection. The following example: - Loads objects, and -- Adds objects to the target collection (`Question`) using a batch process. +- Adds objects to the target collection (`Question`) with a batch import. :::tip Batch imports -([Batch imports](/weaviate/manage-objects/import.mdx)) are the most efficient way to add large amounts of data, as it sends multiple objects in a single request. See the [How-to: Batch import](/weaviate/manage-objects/import.mdx) guide for more information. +Batch imports are the most efficient way to add large amounts of data, because they send objects in groups instead of one request per object. See the [How-to: Batch import](/weaviate/manage-objects/import.mdx) guide for the available methods, including [server-side batching](/weaviate/manage-objects/import.mdx#server-side-batching), where the server tells the client how much data to send next. ::: diff --git a/docs/weaviate/quickstart/local.md b/docs/weaviate/quickstart/local.md index 546e65442..b2059d52b 100644 --- a/docs/weaviate/quickstart/local.md +++ b/docs/weaviate/quickstart/local.md @@ -126,10 +126,6 @@ import CodeClientInstall from "/_includes/code/quickstart/clients.install.new.md ## Step 1: Create a collection & import data {#create-a-collection} -:::info Minimum Weaviate version -The Python and JavaScript/TypeScript examples below import data with [server-side batching](../manage-objects/import.mdx#server-side-batching), which requires Weaviate `v1.36` or later. The Docker Compose file above runs a current release, so this is only a concern if you point the examples at an older instance. -::: - There are two paths you can choose from when importing data: @@ -156,6 +152,10 @@ import CreateCollectionCustomVectors from "/_includes/code/quickstart/quickstart +:::note Requirement: Weaviate v1.36 or later +The `docker-compose.yml` file on this page runs a current Weaviate release, so the examples in this step work as written. The Python and JavaScript/TypeScript examples [import a list of objects in a single call](../manage-objects/import.mdx#ingest-an-in-memory-list), which relies on [server-side batching](../manage-objects/import.mdx#server-side-batching) and needs Weaviate `v1.36` or later. Check the version first if you point the examples at an existing instance. +::: + ## Step 2: Semantic (vector) search {#semantic-search} diff --git a/docs/weaviate/tutorials/quick-tour-of-weaviate.mdx b/docs/weaviate/tutorials/quick-tour-of-weaviate.mdx index 776f338cf..b55c4188f 100644 --- a/docs/weaviate/tutorials/quick-tour-of-weaviate.mdx +++ b/docs/weaviate/tutorials/quick-tour-of-weaviate.mdx @@ -212,11 +212,11 @@ We can now add data to our collection. The following example: - Loads objects, and -- Adds objects to the target collection (`Question`) using a batch process. +- Adds objects to the target collection (`Question`) with a batch import. :::tip Batch imports -([Batch imports](../manage-objects/import.mdx)) are the most efficient way to add large amounts of data, as it sends multiple objects in a single request. See the [How-to: Batch import](../manage-objects/import.mdx) guide for more information. +Batch imports are the most efficient way to add large amounts of data, because they send objects in groups instead of one request per object. See the [How-to: Batch import](../manage-objects/import.mdx) guide for the available methods, including [server-side batching](../manage-objects/import.mdx#server-side-batching), where the server tells the client how much data to send next. ::: From 69f685a8d63ecf6f8ea4eac2382c8af5ba44f98f Mon Sep 17 00:00:00 2001 From: Ivan Despot <66276597+g-despot@users.noreply.github.com> Date: Wed, 29 Jul 2026 15:28:49 +0200 Subject: [PATCH 3/6] docs(quickstart): check result.errors in the Python import step 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. --- _includes/code/python/local.quickstart.import_objects.py | 4 ++-- _includes/code/python/quickstart.import_objects.py | 4 ++-- _includes/code/quickstart/local.quickstart.import_objects.mdx | 2 +- _includes/code/quickstart/quickstart.import_objects.mdx | 2 +- docs/weaviate/quickstart/local.md | 4 ---- 5 files changed, 6 insertions(+), 10 deletions(-) diff --git a/_includes/code/python/local.quickstart.import_objects.py b/_includes/code/python/local.quickstart.import_objects.py index 29e543ddd..2ed338e86 100644 --- a/_includes/code/python/local.quickstart.import_objects.py +++ b/_includes/code/python/local.quickstart.import_objects.py @@ -24,8 +24,8 @@ ) # highlight-end -# Also check `errors` directly; it is populated for every failed object -if result.has_errors or result.errors: +# `errors` is the reliable failure check for `ingest` +if result.errors: print(f"Number of failed imports: {len(result.errors)}") # `errors` is keyed by the position of the object in the input for index, error in result.errors.items(): diff --git a/_includes/code/python/quickstart.import_objects.py b/_includes/code/python/quickstart.import_objects.py index a73ba124d..19055127e 100644 --- a/_includes/code/python/quickstart.import_objects.py +++ b/_includes/code/python/quickstart.import_objects.py @@ -32,8 +32,8 @@ ) # highlight-end -# Also check `errors` directly; it is populated for every failed object -if result.has_errors or result.errors: +# `errors` is the reliable failure check for `ingest` +if result.errors: print(f"Number of failed imports: {len(result.errors)}") # `errors` is keyed by the position of the object in the input for index, error in result.errors.items(): diff --git a/_includes/code/quickstart/local.quickstart.import_objects.mdx b/_includes/code/quickstart/local.quickstart.import_objects.mdx index ab4b5c60c..04601ef67 100644 --- a/_includes/code/quickstart/local.quickstart.import_objects.mdx +++ b/_includes/code/quickstart/local.quickstart.import_objects.mdx @@ -21,7 +21,7 @@ Every import returns a result that reports which objects failed, if any. Check i title="quickstart_import.py" /> -`data.ingest()` returns a `BatchObjectReturn`. Read `result.has_errors` for a quick check, and `result.errors` for one entry per failed object, keyed by its position in the input. For more, see [error handling in the Python client reference](/weaviate/client-libraries/python/notes-best-practices#error-handling). +`data.ingest()` returns a `BatchObjectReturn`. Read `result.errors` to check for failures. It holds one entry per failed object, keyed by its position in the input. For more, see [error handling in the Python client reference](/weaviate/client-libraries/python/notes-best-practices#error-handling). diff --git a/_includes/code/quickstart/quickstart.import_objects.mdx b/_includes/code/quickstart/quickstart.import_objects.mdx index 9104791f2..3b7b8dfc1 100644 --- a/_includes/code/quickstart/quickstart.import_objects.mdx +++ b/_includes/code/quickstart/quickstart.import_objects.mdx @@ -22,7 +22,7 @@ Every import returns a result that reports which objects failed, if any. Check i /> -`data.ingest()` returns a `BatchObjectReturn`. Read `result.has_errors` for a quick check, and `result.errors` for one entry per failed object, keyed by its position in the input. For more, see [error handling in the Python client reference](/weaviate/client-libraries/python/notes-best-practices#error-handling). +`data.ingest()` returns a `BatchObjectReturn`. Read `result.errors` to check for failures. It holds one entry per failed object, keyed by its position in the input. For more, see [error handling in the Python client reference](/weaviate/client-libraries/python/notes-best-practices#error-handling). diff --git a/docs/weaviate/quickstart/local.md b/docs/weaviate/quickstart/local.md index b2059d52b..ea5cd21e1 100644 --- a/docs/weaviate/quickstart/local.md +++ b/docs/weaviate/quickstart/local.md @@ -152,10 +152,6 @@ import CreateCollectionCustomVectors from "/_includes/code/quickstart/quickstart -:::note Requirement: Weaviate v1.36 or later -The `docker-compose.yml` file on this page runs a current Weaviate release, so the examples in this step work as written. The Python and JavaScript/TypeScript examples [import a list of objects in a single call](../manage-objects/import.mdx#ingest-an-in-memory-list), which relies on [server-side batching](../manage-objects/import.mdx#server-side-batching) and needs Weaviate `v1.36` or later. Check the version first if you point the examples at an existing instance. -::: - ## Step 2: Semantic (vector) search {#semantic-search} From e4431ca2ef5e252655177d0761f8c138ebfa9954 Mon Sep 17 00:00:00 2001 From: Ivan Despot <66276597+g-despot@users.noreply.github.com> Date: Thu, 30 Jul 2026 08:51:04 +0200 Subject: [PATCH 4/6] docs(quickstart): use server-side batching in the Java and C# import 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. --- _includes/code/csharp/QuickstartLocalTest.cs | 12 ++++++--- _includes/code/csharp/QuickstartTest.cs | 12 ++++++--- .../csharp/quickstart/QuickstartCreate.cs | 4 +-- .../quickstart/QuickstartCreateVectors.cs | 4 +-- .../quickstart/QuickstartLocalCreate.cs | 4 +-- .../QuickstartLocalCreateVectors.cs | 4 +-- .../src/test/java/QuickstartLocalTest.java | 20 +++++++++------ .../java-v6/src/test/java/QuickstartTest.java | 20 +++++++++------ .../java/quickstart/QuickstartCreate.java | 25 ++++++++++++------- .../quickstart/QuickstartCreateVectors.java | 23 ++++++++++++----- .../quickstart/QuickstartLocalCreate.java | 25 ++++++++++++------- .../QuickstartLocalCreateVectors.java | 22 +++++++++++----- .../local.quickstart.import_objects.mdx | 8 +++++- .../quickstart/quickstart.import_objects.mdx | 8 +++++- 14 files changed, 129 insertions(+), 62 deletions(-) diff --git a/_includes/code/csharp/QuickstartLocalTest.cs b/_includes/code/csharp/QuickstartLocalTest.cs index d6fc27dfc..fac3c4ad7 100644 --- a/_includes/code/csharp/QuickstartLocalTest.cs +++ b/_includes/code/csharp/QuickstartLocalTest.cs @@ -87,21 +87,25 @@ public async Task FullQuickstartWorkflowTest() ); } - // Call InsertMany with the list of objects converted to an array - var insertResponse = await questions.Data.InsertMany(questionsToInsert.ToArray()); + // `Batch.InsertMany` imports the list using server-side batching + var insertResponse = await questions.Batch.InsertMany(questionsToInsert); // highlight-end - // END Import // Check for errors if (insertResponse.HasErrors) { Console.WriteLine($"Number of failed imports: {insertResponse.Errors.Count()}"); - Console.WriteLine($"First failed object error: {insertResponse.Errors.First()}"); + // `Objects` holds one entry per object, in the order they were sent + foreach (var entry in insertResponse.Objects.Where(o => o.Error is not null)) + { + Console.WriteLine($"Failed object at index {entry.Index}: {entry.Error.Message}"); + } } else { Console.WriteLine($"Successfully inserted {insertResponse.Objects.Count()} objects."); } + // END Import // START NearText // highlight-start diff --git a/_includes/code/csharp/QuickstartTest.cs b/_includes/code/csharp/QuickstartTest.cs index 894f41c68..b46a2075e 100644 --- a/_includes/code/csharp/QuickstartTest.cs +++ b/_includes/code/csharp/QuickstartTest.cs @@ -95,21 +95,25 @@ public static async Task FullQuickstartWorkflowTest() ); } - // Call InsertMany with the list of objects converted to an array - var insertResponse = await questions.Data.InsertMany(questionsToInsert.ToArray()); + // `Batch.InsertMany` imports the list using server-side batching + var insertResponse = await questions.Batch.InsertMany(questionsToInsert); // highlight-end - // END Import // Check for errors if (insertResponse.HasErrors) { Console.WriteLine($"Number of failed imports: {insertResponse.Errors.Count()}"); - Console.WriteLine($"First failed object error: {insertResponse.Errors.First()}"); + // `Objects` holds one entry per object, in the order they were sent + foreach (var entry in insertResponse.Objects.Where(o => o.Error is not null)) + { + Console.WriteLine($"Failed object at index {entry.Index}: {entry.Error.Message}"); + } } else { Console.WriteLine($"Successfully inserted {insertResponse.Objects.Count()} objects."); } + // END Import // START NearText // highlight-start diff --git a/_includes/code/csharp/quickstart/QuickstartCreate.cs b/_includes/code/csharp/quickstart/QuickstartCreate.cs index e1a4f4c6f..256d8ff87 100644 --- a/_includes/code/csharp/quickstart/QuickstartCreate.cs +++ b/_includes/code/csharp/quickstart/QuickstartCreate.cs @@ -65,8 +65,8 @@ public static async Task Run() }, }; - // Insert objects using InsertMany - var insertResponse = await movies.Data.InsertMany(dataObjects.ToArray()); + // Insert the objects using server-side batching + var insertResponse = await movies.Batch.InsertMany(dataObjects); if (insertResponse.HasErrors) { diff --git a/_includes/code/csharp/quickstart/QuickstartCreateVectors.cs b/_includes/code/csharp/quickstart/QuickstartCreateVectors.cs index 9ebb7f3d1..330ccd720 100644 --- a/_includes/code/csharp/quickstart/QuickstartCreateVectors.cs +++ b/_includes/code/csharp/quickstart/QuickstartCreateVectors.cs @@ -92,8 +92,8 @@ public static async Task Run() ), }; - // Insert the objects with vectors - var insertResponse = await movies.Data.InsertMany(dataToInsert); + // Insert the objects with vectors using server-side batching + var insertResponse = await movies.Batch.InsertMany(dataToInsert); if (insertResponse.HasErrors) { diff --git a/_includes/code/csharp/quickstart/QuickstartLocalCreate.cs b/_includes/code/csharp/quickstart/QuickstartLocalCreate.cs index 6d00abfb2..cf0f4e75c 100644 --- a/_includes/code/csharp/quickstart/QuickstartLocalCreate.cs +++ b/_includes/code/csharp/quickstart/QuickstartLocalCreate.cs @@ -70,8 +70,8 @@ public static async Task Run() }, }; - // Insert objects using InsertMany - var insertResponse = await movies.Data.InsertMany(dataObjects.ToArray()); + // Insert the objects using server-side batching + var insertResponse = await movies.Batch.InsertMany(dataObjects); if (insertResponse.HasErrors) { diff --git a/_includes/code/csharp/quickstart/QuickstartLocalCreateVectors.cs b/_includes/code/csharp/quickstart/QuickstartLocalCreateVectors.cs index 1e08c3d1b..93cbf8b53 100644 --- a/_includes/code/csharp/quickstart/QuickstartLocalCreateVectors.cs +++ b/_includes/code/csharp/quickstart/QuickstartLocalCreateVectors.cs @@ -76,8 +76,8 @@ public static async Task Run() ), }; - // Insert the objects with vectors - var insertResponse = await movies.Data.InsertMany(dataToInsert); + // Insert the objects with vectors using server-side batching + var insertResponse = await movies.Batch.InsertMany(dataToInsert); if (insertResponse.HasErrors) { Console.WriteLine($"Errors during import: {insertResponse.Errors}"); diff --git a/_includes/code/java-v6/src/test/java/QuickstartLocalTest.java b/_includes/code/java-v6/src/test/java/QuickstartLocalTest.java index c067883b9..0a80c19ca 100644 --- a/_includes/code/java-v6/src/test/java/QuickstartLocalTest.java +++ b/_includes/code/java-v6/src/test/java/QuickstartLocalTest.java @@ -3,7 +3,8 @@ import io.weaviate.client6.v1.api.collections.Generative; import io.weaviate.client6.v1.api.collections.Property; import io.weaviate.client6.v1.api.collections.VectorConfig; -import io.weaviate.client6.v1.api.collections.data.InsertManyResponse; +import io.weaviate.client6.v1.api.collections.WeaviateObject; +import io.weaviate.client6.v1.api.collections.batch.BatchContext; import org.json.JSONArray; import org.json.JSONObject; @@ -94,16 +95,21 @@ void testImportDataWorkflow() throws Exception { questionsToInsert.add(properties); }); - // Call insertMany with the list of objects - InsertManyResponse insertResponse = questions.data.insertMany(questionsToInsert.toArray(new Map[0])); + // `batch.start()` opens a server-side batch + BatchContext> batch = questions.batch.start(); + // Closing the batch sends the remaining objects and waits for the results + try (batch) { + for (Map properties : questionsToInsert) { + batch.add(WeaviateObject.>of(o -> o.properties(properties))); + } + } // highlight-end // Check for errors - if (!insertResponse.errors().isEmpty()) { - System.err.printf("Number of failed imports: %d\n", insertResponse.errors().size()); - System.err.printf("First failed object error: %s\n", insertResponse.errors().get(0)); + if (batch.numberOfErrors() > 0) { + System.err.printf("Number of failed imports: %d\n", batch.numberOfErrors()); } else { - System.out.printf("Successfully inserted %d objects.\n", insertResponse.uuids().size()); + System.out.printf("Successfully inserted %d objects.\n", questionsToInsert.size()); } // END Import // client.collections.delete(collectionName); diff --git a/_includes/code/java-v6/src/test/java/QuickstartTest.java b/_includes/code/java-v6/src/test/java/QuickstartTest.java index 3de3fa0b5..2de260ead 100644 --- a/_includes/code/java-v6/src/test/java/QuickstartTest.java +++ b/_includes/code/java-v6/src/test/java/QuickstartTest.java @@ -3,7 +3,8 @@ import io.weaviate.client6.v1.api.collections.Generative; import io.weaviate.client6.v1.api.collections.Property; import io.weaviate.client6.v1.api.collections.VectorConfig; -import io.weaviate.client6.v1.api.collections.data.InsertManyResponse; +import io.weaviate.client6.v1.api.collections.WeaviateObject; +import io.weaviate.client6.v1.api.collections.batch.BatchContext; import org.json.JSONArray; import org.json.JSONObject; @@ -115,16 +116,21 @@ void testImportDataWorkflow() throws Exception { questionsToInsert.add(properties); }); - // Call insertMany with the list of objects - InsertManyResponse insertResponse = questions.data.insertMany(questionsToInsert.toArray(new Map[0])); + // `batch.start()` opens a server-side batch + BatchContext> batch = questions.batch.start(); + // Closing the batch sends the remaining objects and waits for the results + try (batch) { + for (Map properties : questionsToInsert) { + batch.add(WeaviateObject.>of(o -> o.properties(properties))); + } + } // highlight-end // Check for errors - if (!insertResponse.errors().isEmpty()) { - System.err.printf("Number of failed imports: %d\n", insertResponse.errors().size()); - System.err.printf("First failed object error: %s\n", insertResponse.errors().get(0)); + if (batch.numberOfErrors() > 0) { + System.err.printf("Number of failed imports: %d\n", batch.numberOfErrors()); } else { - System.out.printf("Successfully inserted %d objects.\n", insertResponse.uuids().size()); + System.out.printf("Successfully inserted %d objects.\n", questionsToInsert.size()); } // END Import // client.collections.delete(collectionName); diff --git a/_includes/code/java-v6/src/test/java/quickstart/QuickstartCreate.java b/_includes/code/java-v6/src/test/java/quickstart/QuickstartCreate.java index 745c1049f..d451389b1 100644 --- a/_includes/code/java-v6/src/test/java/quickstart/QuickstartCreate.java +++ b/_includes/code/java-v6/src/test/java/quickstart/QuickstartCreate.java @@ -5,7 +5,8 @@ import io.weaviate.client6.v1.api.collections.CollectionHandle; import io.weaviate.client6.v1.api.collections.Property; import io.weaviate.client6.v1.api.collections.VectorConfig; -import io.weaviate.client6.v1.api.collections.data.InsertManyResponse; +import io.weaviate.client6.v1.api.collections.WeaviateObject; +import io.weaviate.client6.v1.api.collections.batch.BatchContext; import java.util.List; import java.util.Map; @@ -54,18 +55,24 @@ public static void main(String[] args) throws Exception { "A meek Hobbit and his companions set out on a perilous journey to destroy a powerful ring and save Middle-earth.", "genre", "Fantasy")); - // Insert objects using insertMany + // Insert the objects using server-side batching CollectionHandle> movies = client.collections.use(collectionName); - InsertManyResponse insertResponse = - movies.data.insertMany(dataObjects.toArray(new Map[0])); + BatchContext> batch = movies.batch.start(); + // Closing the batch sends the remaining objects and waits for the results + try (batch) { + for (Map properties : dataObjects) { + batch.add( + WeaviateObject.>of(o -> o.properties(properties))); + } + } - if (!insertResponse.errors().isEmpty()) { - System.err.println("Errors during import: " + insertResponse.errors()); + if (batch.numberOfErrors() > 0) { + System.err + .println("Number of failed imports: " + batch.numberOfErrors()); } else { - System.out - .println("Imported & vectorized " + insertResponse.uuids().size() - + " objects into the Movie collection"); + System.out.println("Imported & vectorized " + dataObjects.size() + + " objects into the Movie collection"); } } finally { if (client != null) { diff --git a/_includes/code/java-v6/src/test/java/quickstart/QuickstartCreateVectors.java b/_includes/code/java-v6/src/test/java/quickstart/QuickstartCreateVectors.java index 6a6d930d8..e1f208d41 100644 --- a/_includes/code/java-v6/src/test/java/quickstart/QuickstartCreateVectors.java +++ b/_includes/code/java-v6/src/test/java/quickstart/QuickstartCreateVectors.java @@ -7,7 +7,8 @@ import io.weaviate.client6.v1.api.collections.VectorConfig; import io.weaviate.client6.v1.api.collections.Vectors; import io.weaviate.client6.v1.api.collections.WeaviateObject; -import io.weaviate.client6.v1.api.collections.data.InsertManyResponse; +import io.weaviate.client6.v1.api.collections.batch.BatchContext; +import java.util.List; import java.util.Map; public class QuickstartCreateVectors { @@ -63,20 +64,30 @@ public static void main(String[] args) throws Exception { float[] vector3 = new float[] {0.3f, 0.4f, 0.5f, 0.6f, 0.7f, 0.8f, 0.9f, 1.0f}; - // Insert the objects with vectors + // Insert the objects with vectors using server-side batching CollectionHandle> movies = client.collections.use(collectionName); - InsertManyResponse insertResponse = movies.data.insertMany( + List>> objectsToInsert = List.of( WeaviateObject.of(v -> v.properties(props1) .vectors(Vectors.of(vector1))), WeaviateObject.of(v -> v.properties(props2) .vectors(Vectors.of(vector2))), WeaviateObject.of(v -> v.properties(props3) .vectors(Vectors.of(vector3)))); - if (!insertResponse.errors().isEmpty()) { - System.err.println("Errors during import: " + insertResponse.errors()); + + BatchContext> batch = movies.batch.start(); + // Closing the batch sends the remaining objects and waits for the results + try (batch) { + for (WeaviateObject> object : objectsToInsert) { + batch.add(object); + } + } + + if (batch.numberOfErrors() > 0) { + System.err + .println("Number of failed imports: " + batch.numberOfErrors()); } else { - System.out.println("Imported " + insertResponse.uuids().size() + System.out.println("Imported " + objectsToInsert.size() + " objects with vectors into the Movie collection"); } } finally { diff --git a/_includes/code/java-v6/src/test/java/quickstart/QuickstartLocalCreate.java b/_includes/code/java-v6/src/test/java/quickstart/QuickstartLocalCreate.java index 16e7149be..6b6b45477 100644 --- a/_includes/code/java-v6/src/test/java/quickstart/QuickstartLocalCreate.java +++ b/_includes/code/java-v6/src/test/java/quickstart/QuickstartLocalCreate.java @@ -5,7 +5,8 @@ import io.weaviate.client6.v1.api.collections.CollectionHandle; import io.weaviate.client6.v1.api.collections.Property; import io.weaviate.client6.v1.api.collections.VectorConfig; -import io.weaviate.client6.v1.api.collections.data.InsertManyResponse; +import io.weaviate.client6.v1.api.collections.WeaviateObject; +import io.weaviate.client6.v1.api.collections.batch.BatchContext; import java.util.List; import java.util.Map; @@ -53,18 +54,24 @@ public static void main(String[] args) throws Exception { "A meek Hobbit and his companions set out on a perilous journey to destroy a powerful ring and save Middle-earth.", "genre", "Fantasy")); - // Insert objects using insertMany + // Insert the objects using server-side batching CollectionHandle> movies = client.collections.use(collectionName); - InsertManyResponse insertResponse = - movies.data.insertMany(dataObjects.toArray(new Map[0])); + BatchContext> batch = movies.batch.start(); + // Closing the batch sends the remaining objects and waits for the results + try (batch) { + for (Map properties : dataObjects) { + batch.add( + WeaviateObject.>of(o -> o.properties(properties))); + } + } - if (!insertResponse.errors().isEmpty()) { - System.err.println("Errors during import: " + insertResponse.errors()); + if (batch.numberOfErrors() > 0) { + System.err + .println("Number of failed imports: " + batch.numberOfErrors()); } else { - System.out - .println("Imported & vectorized " + insertResponse.uuids().size() - + " objects into the Movie collection"); + System.out.println("Imported & vectorized " + dataObjects.size() + + " objects into the Movie collection"); } } finally { if (client != null) { diff --git a/_includes/code/java-v6/src/test/java/quickstart/QuickstartLocalCreateVectors.java b/_includes/code/java-v6/src/test/java/quickstart/QuickstartLocalCreateVectors.java index f31eaad3d..66c88691d 100644 --- a/_includes/code/java-v6/src/test/java/quickstart/QuickstartLocalCreateVectors.java +++ b/_includes/code/java-v6/src/test/java/quickstart/QuickstartLocalCreateVectors.java @@ -7,7 +7,8 @@ import io.weaviate.client6.v1.api.collections.VectorConfig; import io.weaviate.client6.v1.api.collections.Vectors; import io.weaviate.client6.v1.api.collections.WeaviateObject; -import io.weaviate.client6.v1.api.collections.data.InsertManyResponse; +import io.weaviate.client6.v1.api.collections.batch.BatchContext; +import java.util.List; import java.util.Map; public class QuickstartLocalCreateVectors { @@ -59,10 +60,10 @@ public static void main(String[] args) throws Exception { float[] vector3 = new float[] {0.3f, 0.4f, 0.5f, 0.6f, 0.7f, 0.8f, 0.9f, 1.0f}; - // Insert the objects with vectors + // Insert the objects with vectors using server-side batching CollectionHandle> movies = client.collections.use(collectionName); - InsertManyResponse insertResponse = movies.data.insertMany( + List>> objectsToInsert = List.of( WeaviateObject.of(v -> v.properties(props1) .vectors(Vectors.of(vector1))), WeaviateObject.of(v -> v.properties(props2) @@ -70,10 +71,19 @@ public static void main(String[] args) throws Exception { WeaviateObject.of(v -> v.properties(props3) .vectors(Vectors.of(vector3)))); - if (!insertResponse.errors().isEmpty()) { - System.err.println("Errors during import: " + insertResponse.errors()); + BatchContext> batch = movies.batch.start(); + // Closing the batch sends the remaining objects and waits for the results + try (batch) { + for (WeaviateObject> object : objectsToInsert) { + batch.add(object); + } + } + + if (batch.numberOfErrors() > 0) { + System.err + .println("Number of failed imports: " + batch.numberOfErrors()); } else { - System.out.println("Imported " + insertResponse.uuids().size() + System.out.println("Imported " + objectsToInsert.size() + " objects with vectors into the Movie collection"); } } finally { diff --git a/_includes/code/quickstart/local.quickstart.import_objects.mdx b/_includes/code/quickstart/local.quickstart.import_objects.mdx index 04601ef67..d4550c2de 100644 --- a/_includes/code/quickstart/local.quickstart.import_objects.mdx +++ b/_includes/code/quickstart/local.quickstart.import_objects.mdx @@ -8,7 +8,7 @@ import JavaV6Code from "!!raw-loader!/_includes/code/java-v6/src/test/java/Quick import CSharpCode from "!!raw-loader!/_includes/code/csharp/QuickstartLocalTest.cs"; -Every import returns a result that reports which objects failed, if any. Check it in your own code to catch problems such as malformed data or a misconfigured model provider. +Every import returns a result that reports whether any objects failed. Check it in your own code to catch problems such as malformed data or a misconfigured model provider. @@ -56,6 +56,9 @@ Every import returns a result that reports which objects failed, if any. Check i endMarker="// END Import" language="java" /> + +`batch.start()` opens a server-side batch. Closing the batch sends any remaining objects and waits for the server to report the results, so read `batch.numberOfErrors()` afterwards for the number of objects that failed. + @@ -65,6 +68,9 @@ Every import returns a result that reports which objects failed, if any. Check i endMarker="// END Import" language="csharp" /> + +`Batch.InsertMany()` returns a `BatchInsertResponse`. Read `HasErrors` for a quick check, and `Objects` for one entry per object, each carrying the `Error` that failed it. + diff --git a/_includes/code/quickstart/quickstart.import_objects.mdx b/_includes/code/quickstart/quickstart.import_objects.mdx index 3b7b8dfc1..4aee756d0 100644 --- a/_includes/code/quickstart/quickstart.import_objects.mdx +++ b/_includes/code/quickstart/quickstart.import_objects.mdx @@ -8,7 +8,7 @@ import JavaV6Code from "!!raw-loader!/_includes/code/java-v6/src/test/java/Quick import CSharpCode from "!!raw-loader!/_includes/code/csharp/QuickstartTest.cs"; -Every import returns a result that reports which objects failed, if any. Check it in your own code to catch problems such as malformed data or a misconfigured model provider. +Every import returns a result that reports whether any objects failed. Check it in your own code to catch problems such as malformed data or a misconfigured model provider. @@ -57,6 +57,9 @@ Every import returns a result that reports which objects failed, if any. Check i endMarker="// END Import" language="java" /> + +`batch.start()` opens a server-side batch. Closing the batch sends any remaining objects and waits for the server to report the results, so read `batch.numberOfErrors()` afterwards for the number of objects that failed. + @@ -66,6 +69,9 @@ Every import returns a result that reports which objects failed, if any. Check i endMarker="// END Import" language="csharp" /> + +`Batch.InsertMany()` returns a `BatchInsertResponse`. Read `HasErrors` for a quick check, and `Objects` for one entry per object, each carrying the `Error` that failed it. + From ffd62a366253006ca96e200a5c06f593e3991f47 Mon Sep 17 00:00:00 2001 From: Ivan Despot <66276597+g-despot@users.noreply.github.com> Date: Thu, 30 Jul 2026 09:59:53 +0200 Subject: [PATCH 5/6] docs(quickstart): correct the import prose for Java and C# 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()`. --- _includes/code/csharp/QuickstartLocalTest.cs | 4 ++-- _includes/code/csharp/QuickstartTest.cs | 4 ++-- .../code/quickstart/local.quickstart.import_objects.mdx | 6 +++--- _includes/code/quickstart/quickstart.import_objects.mdx | 7 +++---- 4 files changed, 10 insertions(+), 11 deletions(-) diff --git a/_includes/code/csharp/QuickstartLocalTest.cs b/_includes/code/csharp/QuickstartLocalTest.cs index fac3c4ad7..6f9e71eb5 100644 --- a/_includes/code/csharp/QuickstartLocalTest.cs +++ b/_includes/code/csharp/QuickstartLocalTest.cs @@ -95,7 +95,7 @@ public async Task FullQuickstartWorkflowTest() if (insertResponse.HasErrors) { Console.WriteLine($"Number of failed imports: {insertResponse.Errors.Count()}"); - // `Objects` holds one entry per object, in the order they were sent + // `Objects` holds one entry per object; `Index` is the position of the object in the input foreach (var entry in insertResponse.Objects.Where(o => o.Error is not null)) { Console.WriteLine($"Failed object at index {entry.Index}: {entry.Error.Message}"); @@ -103,7 +103,7 @@ public async Task FullQuickstartWorkflowTest() } else { - Console.WriteLine($"Successfully inserted {insertResponse.Objects.Count()} objects."); + Console.WriteLine($"Successfully inserted {insertResponse.Count} objects."); } // END Import diff --git a/_includes/code/csharp/QuickstartTest.cs b/_includes/code/csharp/QuickstartTest.cs index b46a2075e..07a144781 100644 --- a/_includes/code/csharp/QuickstartTest.cs +++ b/_includes/code/csharp/QuickstartTest.cs @@ -103,7 +103,7 @@ public static async Task FullQuickstartWorkflowTest() if (insertResponse.HasErrors) { Console.WriteLine($"Number of failed imports: {insertResponse.Errors.Count()}"); - // `Objects` holds one entry per object, in the order they were sent + // `Objects` holds one entry per object; `Index` is the position of the object in the input foreach (var entry in insertResponse.Objects.Where(o => o.Error is not null)) { Console.WriteLine($"Failed object at index {entry.Index}: {entry.Error.Message}"); @@ -111,7 +111,7 @@ public static async Task FullQuickstartWorkflowTest() } else { - Console.WriteLine($"Successfully inserted {insertResponse.Objects.Count()} objects."); + Console.WriteLine($"Successfully inserted {insertResponse.Count} objects."); } // END Import diff --git a/_includes/code/quickstart/local.quickstart.import_objects.mdx b/_includes/code/quickstart/local.quickstart.import_objects.mdx index d4550c2de..ad0c6222f 100644 --- a/_includes/code/quickstart/local.quickstart.import_objects.mdx +++ b/_includes/code/quickstart/local.quickstart.import_objects.mdx @@ -8,7 +8,7 @@ import JavaV6Code from "!!raw-loader!/_includes/code/java-v6/src/test/java/Quick import CSharpCode from "!!raw-loader!/_includes/code/csharp/QuickstartLocalTest.cs"; -Every import returns a result that reports whether any objects failed. Check it in your own code to catch problems such as malformed data or a misconfigured model provider. +Every import reports whether any objects failed. Check for failures in your own code to catch problems such as malformed data or a misconfigured model provider. @@ -57,7 +57,7 @@ Every import returns a result that reports whether any objects failed. Check it language="java" /> -`batch.start()` opens a server-side batch. Closing the batch sends any remaining objects and waits for the server to report the results, so read `batch.numberOfErrors()` afterwards for the number of objects that failed. +`batch.start()` opens a server-side batch. Closing the batch sends any remaining objects and waits for the server to report the results. Read `batch.numberOfErrors()` after the batch closes; before then, the tally is incomplete. @@ -69,7 +69,7 @@ Every import returns a result that reports whether any objects failed. Check it language="csharp" /> -`Batch.InsertMany()` returns a `BatchInsertResponse`. Read `HasErrors` for a quick check, and `Objects` for one entry per object, each carrying the `Error` that failed it. +`Batch.InsertMany()` returns a `BatchInsertResponse`. Read `HasErrors` for a quick check, `Errors` for the failures alone, and `Objects` for one entry per object. Each entry's `Index` is its position in the input, and failed entries carry an `Error`. diff --git a/_includes/code/quickstart/quickstart.import_objects.mdx b/_includes/code/quickstart/quickstart.import_objects.mdx index 4aee756d0..5ca38bfca 100644 --- a/_includes/code/quickstart/quickstart.import_objects.mdx +++ b/_includes/code/quickstart/quickstart.import_objects.mdx @@ -8,7 +8,7 @@ import JavaV6Code from "!!raw-loader!/_includes/code/java-v6/src/test/java/Quick import CSharpCode from "!!raw-loader!/_includes/code/csharp/QuickstartTest.cs"; -Every import returns a result that reports whether any objects failed. Check it in your own code to catch problems such as malformed data or a misconfigured model provider. +Every import reports whether any objects failed. Check for failures in your own code to catch problems such as malformed data or a misconfigured model provider. @@ -21,7 +21,6 @@ Every import returns a result that reports whether any objects failed. Check it title="quickstart_import.py" /> - `data.ingest()` returns a `BatchObjectReturn`. Read `result.errors` to check for failures. It holds one entry per failed object, keyed by its position in the input. For more, see [error handling in the Python client reference](/weaviate/client-libraries/python/notes-best-practices#error-handling). @@ -58,7 +57,7 @@ Every import returns a result that reports whether any objects failed. Check it language="java" /> -`batch.start()` opens a server-side batch. Closing the batch sends any remaining objects and waits for the server to report the results, so read `batch.numberOfErrors()` afterwards for the number of objects that failed. +`batch.start()` opens a server-side batch. Closing the batch sends any remaining objects and waits for the server to report the results. Read `batch.numberOfErrors()` after the batch closes; before then, the tally is incomplete. @@ -70,7 +69,7 @@ Every import returns a result that reports whether any objects failed. Check it language="csharp" /> -`Batch.InsertMany()` returns a `BatchInsertResponse`. Read `HasErrors` for a quick check, and `Objects` for one entry per object, each carrying the `Error` that failed it. +`Batch.InsertMany()` returns a `BatchInsertResponse`. Read `HasErrors` for a quick check, `Errors` for the failures alone, and `Objects` for one entry per object. Each entry's `Index` is its position in the input, and failed entries carry an `Error`. From 9436d6b84d09de595ecf7440db1f90ffa1a4c4fd Mon Sep 17 00:00:00 2001 From: Ivan Despot <66276597+g-despot@users.noreply.github.com> Date: Thu, 30 Jul 2026 11:05:37 +0200 Subject: [PATCH 6/6] docs(quickstart): merge the two `errors` comments in the Python import Both comments described the same dictionary. Replace them with a single line above the check that says what `errors` holds and how it is keyed, matching the prose under the snippet. --- _includes/code/python/local.quickstart.import_objects.py | 3 +-- _includes/code/python/quickstart.import_objects.py | 3 +-- 2 files changed, 2 insertions(+), 4 deletions(-) diff --git a/_includes/code/python/local.quickstart.import_objects.py b/_includes/code/python/local.quickstart.import_objects.py index 2ed338e86..d46b4dd1c 100644 --- a/_includes/code/python/local.quickstart.import_objects.py +++ b/_includes/code/python/local.quickstart.import_objects.py @@ -24,10 +24,9 @@ ) # highlight-end -# `errors` is the reliable failure check for `ingest` +# `errors` holds one entry per failed object, keyed by its position in the input if result.errors: print(f"Number of failed imports: {len(result.errors)}") - # `errors` is keyed by the position of the object in the input for index, error in result.errors.items(): print(f"Failed object at index {index}: {error.message}") diff --git a/_includes/code/python/quickstart.import_objects.py b/_includes/code/python/quickstart.import_objects.py index 19055127e..0f4041af9 100644 --- a/_includes/code/python/quickstart.import_objects.py +++ b/_includes/code/python/quickstart.import_objects.py @@ -32,10 +32,9 @@ ) # highlight-end -# `errors` is the reliable failure check for `ingest` +# `errors` holds one entry per failed object, keyed by its position in the input if result.errors: print(f"Number of failed imports: {len(result.errors)}") - # `errors` is keyed by the position of the object in the input for index, error in result.errors.items(): print(f"Failed object at index {index}: {error.message}")