The batch API from Weaviate — 2 operation(s) for batch.
openapi: 3.0.3
info:
title: Weaviate REST authz batch API
description: '# Introduction<br/> Weaviate is an open source, AI-native vector database that helps developers create intuitive and reliable AI-powered applications. <br/> ### Base Path <br/>The base path for the Weaviate server is structured as `[YOUR-WEAVIATE-HOST]:[PORT]/v1`. As an example, if you wish to access the `schema` endpoint on a local instance, you would navigate to `http://localhost:8080/v1/schema`. Ensure you replace `[YOUR-WEAVIATE-HOST]` and `[PORT]` with your actual server host and port number respectively. <br/> ### Questions? <br/>If you have any comments or questions, please feel free to reach out to us at the community forum [https://forum.weaviate.io/](https://forum.weaviate.io/). <br/>### Issues? <br/>If you find a bug or want to file a feature request, please open an issue on our GitHub repository for [Weaviate](https://github.com/weaviate/weaviate). <br/>### Need more documentation? <br/>For a quickstart, code examples, concepts and more, please visit our [documentation page](https://docs.weaviate.io/weaviate).'
version: 1.38.0-dev
servers:
- url: http://localhost:8080
description: Local Weaviate instance
security:
- ApiKeyAuth: []
- BearerAuth: []
tags:
- name: batch
paths:
/batch/objects:
post:
summary: Weaviate Create Objects In Batch
description: Registers multiple data objects in a single request for efficiency. Metadata and schema values for each object are validated.<br/><br/>**Note (idempotence)**:<br/>This operation is idempotent based on the object UUIDs provided. If an object with a given UUID already exists, it will be overwritten (similar to a PUT operation for that specific object within the batch).
tags:
- batch
operationId: batch.objects.create
parameters:
- name: consistency_level
in: query
required: false
description: Determines how many replicas must acknowledge a request before it is considered successful.
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
fields:
type: array
description: Controls which fields are returned in the response for each object. Default is `ALL`.
items:
type: string
enum:
- ALL
- class
- schema
- id
- creationTimeUnix
default: ALL
objects:
type: array
description: Array of objects to be created.
items:
$ref: '#/components/schemas/Object'
responses:
'200':
description: Request processed successfully. Individual object statuses are provided in the response body.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ObjectsGetResponse'
'400':
description: Malformed request.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized or invalid credentials.
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'422':
description: The request syntax is correct, but the server couldn't process it due to semantic issues. Please check the values in your request. Ensure the collection exists and the object properties are valid.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: An error occurred while trying to fulfill the request. Check the ErrorResponse for details.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
x-microcks-operation:
delay: 100
delete:
summary: Weaviate Delete Objects In Batch
description: Removes multiple data objects based on a filter specified in the request body.<br/><br/>Deletion occurs based on the filter criteria provided in the `where` clause. There is a configurable limit (default 10,000, set via `QUERY_MAXIMUM_RESULTS`) on how many objects can be deleted in a single batch request to prevent excessive resource usage. Objects are deleted in the order they match the filter. To delete more objects than the limit allows, repeat the request until no more matching objects are found.
tags:
- batch
operationId: batch.objects.delete
parameters:
- name: consistency_level
in: query
required: false
description: Determines how many replicas must acknowledge a request before it is considered successful.
schema:
type: string
- name: tenant
in: query
required: false
description: Specifies the tenant in a request targeting a multi-tenant collection (class).
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/BatchDelete'
responses:
'200':
description: Request processed successfully. See response body for matching objects and deletion results.
content:
application/json:
schema:
$ref: '#/components/schemas/BatchDeleteResponse'
'400':
description: Malformed request.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized or invalid credentials.
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'422':
description: Invalid data provided. Please check the values in your request (e.g., invalid filter).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: An error occurred while trying to fulfill the request. Check the ErrorResponse for details.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
x-microcks-operation:
delay: 100
/batch/references:
post:
summary: Weaviate Create Cross-References In Bulk
description: Batch create cross-references between collection items in bulk.
tags:
- batch
operationId: batch.references.create
parameters:
- name: consistency_level
in: query
required: false
description: Determines how many replicas must acknowledge a request before it is considered successful.
schema:
type: string
requestBody:
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/BatchReference'
responses:
'200':
description: 'Request Successful. Warning: A successful request does not guarantee that every batched reference was successfully created. Inspect the response body to see which references succeeded and which failed.'
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/BatchReferenceResponse'
'400':
description: Malformed request.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized or invalid credentials.
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'422':
description: The request syntax is correct, but the server couldn't process it due to semantic issues. Please check the values in your request. Ensure the collection exists and the object properties are valid.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: An error has occurred while trying to fulfill the request. Most likely the ErrorResponse will contain more information about the error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
x-microcks-operation:
delay: 100
components:
schemas:
AdditionalProperties:
type: object
description: (Response only) Additional meta information about a single object.
additionalProperties:
type: object
Deprecation:
type: object
properties:
id:
type: string
description: The id that uniquely identifies this particular deprecation (mostly used internally).
status:
type: string
description: Whether the problematic API functionality is deprecated (planned to be removed) or already removed.
apiType:
type: string
description: 'Describes which API is affected, usually one of: REST, GraphQL and gRPC.'
msg:
type: string
description: What this deprecation is about.
mitigation:
type: string
description: User-required object to not be affected by the (planned) removal.
sinceVersion:
type: string
description: The deprecation was introduced in this version.
plannedRemovalVersion:
type: string
description: A best-effort guess of which upcoming version will remove the feature entirely.
removedIn:
type: string
description: If the feature has already been removed, it was removed in this version.
removedTime:
type: string
format: date-time
description: If the feature has already been removed, it was removed at this timestamp.
sinceTime:
type: string
format: date-time
description: The deprecation was introduced at this timestamp.
locations:
type: array
description: The locations within the specified API affected by this deprecation.
items:
type: string
C11yVector:
type: array
description: A vector representation of the object in the Contextionary. If provided at object creation, this wil take precedence over any vectorizer setting.
items:
type: number
format: float
WhereFilterGeoRange:
type: object
description: Filter within a distance of a georange.
properties:
geoCoordinates:
$ref: '#/components/schemas/GeoCoordinates'
distance:
type: object
properties:
max:
type: number
format: float64
BatchDeleteResponse:
type: object
description: Delete Objects response.
properties:
match:
type: object
description: Outlines how to find the objects to be deleted.
properties:
class:
type: string
description: The name of the collection (class) from which to delete objects.
example: City
where:
$ref: '#/components/schemas/WhereFilter'
output:
type: string
description: 'Controls the verbosity of the output, possible values are: `minimal`, `verbose`. Defaults to `minimal`.'
default: minimal
deletionTimeUnixMilli:
type: integer
format: int64
description: Timestamp of deletion in milliseconds since epoch UTC.
dryRun:
type: boolean
description: If true, objects will not be deleted yet, but merely listed. Defaults to false.
default: false
results:
type: object
properties:
matches:
type: number
format: int64
description: How many objects were matched by the filter.
limit:
type: number
format: int64
description: The most amount of objects that can be deleted in a single query, equals [`QUERY_MAXIMUM_RESULTS`](https://docs.weaviate.io/deploy/configuration/env-vars#QUERY_MAXIMUM_RESULTS).
successful:
type: number
format: int64
description: How many objects were successfully deleted in this round.
failed:
type: number
format: int64
description: How many objects should have been deleted but could not be deleted.
objects:
type: array
description: With output set to `minimal` only objects with error occurred will the be described. Successfully deleted objects would be omitted. Output set to `verbose` will list all of the objects with their respective statuses.
items:
format: object
description: Results for this specific Object.
properties:
id:
type: string
format: uuid
description: The UUID of the object.
status:
type: string
enum:
- SUCCESS
- DRYRUN
- FAILED
default: SUCCESS
errors:
$ref: '#/components/schemas/ErrorResponse'
Object:
type: object
properties:
class:
type: string
description: Name of the collection (class) the object belongs to.
vectorWeights:
$ref: '#/components/schemas/VectorWeights'
properties:
$ref: '#/components/schemas/PropertySchema'
id:
type: string
format: uuid
description: The UUID of the object.
creationTimeUnix:
type: integer
format: int64
description: (Response only) Timestamp of creation of this object in milliseconds since epoch UTC.
lastUpdateTimeUnix:
type: integer
format: int64
description: (Response only) Timestamp of the last object update in milliseconds since epoch UTC.
vector:
$ref: '#/components/schemas/C11yVector'
vectors:
$ref: '#/components/schemas/Vectors'
tenant:
type: string
description: The name of the tenant the object belongs to.
additional:
$ref: '#/components/schemas/AdditionalProperties'
PropertySchema:
type: object
description: Names and values of an individual property. A returned response may also contain additional metadata, such as from classification or feature projection.
BatchDelete:
type: object
properties:
match:
type: object
description: Outlines how to find the objects to be deleted.
properties:
class:
type: string
description: The name of the collection (class) from which to delete objects.
example: City
where:
$ref: '#/components/schemas/WhereFilter'
output:
type: string
description: 'Controls the verbosity of the output, possible values are: `minimal`, `verbose`. Defaults to `minimal`.'
default: minimal
deletionTimeUnixMilli:
type: integer
format: int64
description: Timestamp of deletion in milliseconds since epoch UTC.
dryRun:
type: boolean
description: If true, the call will show which objects would be matched using the specified filter without deleting any objects. <br/><br/>Depending on the configured verbosity, you will either receive a count of affected objects, or a list of IDs.
default: false
GeoCoordinates:
properties:
latitude:
type: number
format: float
description: The latitude of the point on earth in decimal form.
longitude:
type: number
format: float
description: The longitude of the point on earth in decimal form.
Vector:
type: object
description: A vector representation of the object. If provided at object creation, this wil take precedence over any vectorizer setting.
VectorWeights:
type: object
description: 'Allow custom overrides of vector weights as math expressions. E.g. `pancake`: `7` will set the weight for the word pancake to 7 in the vectorization, whereas `w * 3` would triple the originally calculated word. This is an open object, with OpenAPI Specification 3.0 this will be more detailed. See Weaviate docs for more info. In the future this will become a key/value (string/string) object.'
WhereFilter:
type: object
description: Filter search results using a where filter.
properties:
operands:
type: array
description: Combine multiple where filters, requires 'And' or 'Or' operator.
items:
$ref: '#/components/schemas/WhereFilter'
operator:
type: string
description: Operator to use.
enum:
- And
- Or
- Equal
- Like
- NotEqual
- GreaterThan
- GreaterThanEqual
- LessThan
- LessThanEqual
- WithinGeoRange
- IsNull
- ContainsAny
- ContainsAll
- ContainsNone
- Not
example: GreaterThanEqual
path:
type: array
description: Path to the property currently being filtered.
example:
- inCity
- city
- name
items:
type: string
valueInt:
type: integer
format: int64
description: value as integer
example: 2000
valueNumber:
type: number
format: float64
description: value as number/float
example: 3.14
valueBoolean:
type: boolean
description: value as boolean
example: false
valueString:
type: string
description: value as text (deprecated as of v1.19; alias for valueText)
example: my search term
valueText:
type: string
description: value as text
example: my search term
valueDate:
type: string
description: value as date (as string)
example: TODO
valueIntArray:
type: array
description: value as integer
example: '[100, 200]'
items:
type: integer
format: int64
valueNumberArray:
type: array
description: value as number/float
example:
- 3.14
items:
type: number
format: float64
valueBooleanArray:
type: array
description: value as boolean
example:
- true
- false
items:
type: boolean
valueStringArray:
type: array
description: value as text (deprecated as of v1.19; alias for valueText)
example:
- my search term
items:
type: string
valueTextArray:
type: array
description: value as text
example:
- my search term
items:
type: string
valueDateArray:
type: array
description: value as date (as string)
example: TODO
items:
type: string
valueGeoRange:
$ref: '#/components/schemas/WhereFilterGeoRange'
ObjectsGetResponse:
allOf:
- $ref: '#/components/schemas/Object'
- properties:
deprecations:
type: array
items:
$ref: '#/components/schemas/Deprecation'
- properties:
result:
format: object
description: Results for this specific object.
properties:
status:
type: string
enum:
- SUCCESS
- FAILED
default: SUCCESS
errors:
$ref: '#/components/schemas/ErrorResponse'
ErrorResponse:
type: object
description: An error response returned by Weaviate endpoints.
properties:
error:
type: array
items:
type: object
properties:
message:
type: string
BatchReferenceResponse:
allOf:
- $ref: '#/components/schemas/BatchReference'
- properties:
result:
format: object
description: Results for this specific reference.
properties:
status:
type: string
enum:
- SUCCESS
- FAILED
default: SUCCESS
errors:
$ref: '#/components/schemas/ErrorResponse'
BatchReference:
properties:
from:
type: string
format: uri
description: Long-form beacon-style URI to identify the source of the cross-reference, including the property name. Should be in the form of `weaviate://localhost/objects/<uuid>/<className>/<propertyName>`, where `<className>` and `<propertyName>` must represent the cross-reference property of the source class to be used.
example: weaviate://localhost/Zoo/a5d09582-4239-4702-81c9-92a6e0122bb4/hasAnimals
to:
type: string
format: uri
description: Short-form URI to point to the cross-reference. Should be in the form of `weaviate://localhost/<uuid>` for the example of a local cross-reference to an object.
example: weaviate://localhost/97525810-a9a5-4eb0-858a-71449aeb007f
tenant:
type: string
description: Name of the reference tenant.
Vectors:
type: object
description: A map of named vectors for multi-vector representations.
additionalProperties:
$ref: '#/components/schemas/Vector'
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: Authorization
description: API key authentication
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: OIDC/JWT bearer authentication