weaviate.gql package
GraphQL module used to create get and/or aggregate GraphQL requests from Weaviate.
- class weaviate.gql.AdditionalProperties(uuid: bool = False, vector: bool = False, creationTimeUnix: bool = False, lastUpdateTimeUnix: bool = False, distance: bool = False, certainty: bool = False, score: bool = False, explainScore: bool = False)[source]
Bases:
object
- certainty: bool = False
- creationTimeUnix: bool = False
- distance: bool = False
- explainScore: bool = False
- lastUpdateTimeUnix: bool = False
- score: bool = False
- uuid: bool = False
- vector: bool = False
- class weaviate.gql.LinkTo(link_on: str, linked_class: str, properties: Sequence[Union[str, ForwardRef('LinkTo')]])[source]
Bases:
object
- link_on: str
- linked_class: str
- class weaviate.gql.Query(connection: Connection)[source]
Bases:
object
Query class used to make get and/or aggregate GraphQL queries.
Initialize a Classification class instance.
Parameters
- connectionweaviate.connect.Connection
Connection object to an active and running Weaviate instance.
- aggregate(class_name: str) AggregateBuilder [source]
Instantiate an AggregateBuilder for GraphQL aggregate requests.
Parameters
- class_namestr
Class name of the objects to be aggregated.
Returns
- AggregateBuilder
An AggregateBuilder to make GraphQL aggregate requests from weaviate.
- get(class_name: str, properties: Sequence[str | LinkTo] | str | None = None) GetBuilder [source]
Instantiate a GetBuilder for GraphQL get requests.
Parameters
- class_namestr
Class name of the objects to interact with.
- propertieslist of str and ReferenceProperty, str or None
Properties of the objects to get, by default None
Returns
- GetBuilder
A GetBuilder to make GraphQL get requests from weaviate.
- multi_get(get_builder: List[GetBuilder]) MultiGetBuilder [source]
Instantiate a MultiGetBuilder for GraphQL multi_get requests. Bundles multiple get requests into one.
Parameters
- get_builderlist of GetBuilder
List of GetBuilder objects for a single request each.
Returns
- MultiGetBuilder
A MultiGetBuilder to make GraphQL get multiple requests from weaviate.
- raw(gql_query: str) Dict[str, Any] [source]
Allows to send simple graph QL string queries. Be cautious of injection risks when generating query strings.
Parameters
- gql_querystr
GraphQL query as a string.
Returns
- dict
Data response of the query.
Examples
>>> query = """ ... { ... Get { ... Article(limit: 2) { ... title ... hasAuthors { ... ... on Author { ... name ... } ... } ... } ... } ... } ... """ >>> client.query.raw(query) { "data": { "Get": { "Article": [ { "hasAuthors": [ { "name": "Jonathan Wilson" } ], "title": "Sergio Agüero has been far more than a great goalscorer for Manchester City" }, { "hasAuthors": [ { "name": "Emma Elwick-Bates" } ], "title": "At Swarovski, Giovanna Engelbert Is Crafting Jewels As Exuberantly Joyful As She Is" } ] } }, "errors": null }
Raises
- TypeError
If ‘gql_query’ is not of type str.
- requests.ConnectionError
If the network connection to weaviate fails.
- weaviate.UnexpectedStatusCodeException
If weaviate reports a none OK status.
Submodules
weaviate.gql.aggregate module
GraphQL Aggregate command.
- class weaviate.gql.aggregate.AggregateBuilder(class_name: str, connection: Connection | ConnectionV4)[source]
Bases:
GraphQL
AggregateBuilder class used to aggregate Weaviate objects.
Initialize a AggregateBuilder class instance.
Parameters
- class_namestr
Class name of the objects to be aggregated.
- connectionweaviate.connect.Connection
Connection object to an active and running Weaviate instance.
- build() str [source]
Build the query and return the string.
Returns
- str
The GraphQL query as a string.
- with_fields(field: str) AggregateBuilder [source]
Include a field in the aggregate query.
Parameters
- fieldstr
Field to include in the aggregate query. e.g. ‘<property_name> { count }’
Returns
- weaviate.gql.aggregate.AggregateBuilder
Updated AggregateBuilder.
- with_group_by_filter(properties: List[str]) AggregateBuilder [source]
Add a group by filter to the query. Might requires the user to set an additional group by clause using with_fields(..).
Parameters
- propertieslist of str
list of properties that are included in the group by filter. Generates a filter like: ‘groupBy: [“property1”, “property2”]’ from a list [“property1”, “property2”]
Returns
- weaviate.gql.aggregate.AggregateBuilder
Updated AggregateBuilder.
- with_limit(limit: int) AggregateBuilder [source]
Set limit to limit the number of returned results from the aggregation query.
Parameters
- limitint
The limit.
Returns
- weaviate.gql.aggregate.AggregateBuilder
Updated AggregateBuilder.
- with_meta_count() AggregateBuilder [source]
Set Meta Count to True.
Returns
- weaviate.gql.aggregate.AggregateBuilder
Updated AggregateBuilder.
- with_near_audio(content: dict, encode: bool = True) AggregateBuilder [source]
Set nearAudio filter.
Parameters
- contentdict
The content of the nearAudio filter to set. See examples below.
- encodebool, optional
Whether to encode the content[“audio”] to base64 and convert to string. If True, the content[“audio”] can be an audio path or a file opened in binary read mode. If False, the content[“audio”] MUST be a base64 encoded string (NOT bytes, i.e. NOT binary string that looks like this: b’BASE64ENCODED’ but simple ‘BASE64ENCODED’). By default True.
Examples
Content prototype:
>>> content = { ... 'audio': <str or binary read file>, ... # certainty ONLY with `cosine` distance specified in the schema ... 'certainty': <float>, # Optional, either 'certainty' OR 'distance' ... 'distance': <float>, # Optional, either 'certainty' OR 'distance' ... }
>>> { ... 'audio': "e5dc4a4c-ef0f-3aed-89a3-a73435c6bbcf", ... 'certainty': 0.7 # or 'distance' ... }
With encoded True:
>>> content = { ... 'audio': "my_audio_path.wav", ... 'certainty': 0.7 # or 'distance' instead ... } >>> query = client.query.aggregate('Audio')\ .with_fields('description')\ ... .with_near_audio(content, encode=True) # <- encode MUST be set to True
OR
>>> my_audio_file = open("my_audio_path.wav", "br") >>> content = { ... 'audio': my_audio_file, ... 'certainty': 0.7 # or 'distance' instead ... } >>> query = client.query.aggregate('Audio')\ .with_fields('description')\ ... .with_near_audio(content, encode=True) # <- encode MUST be set to True >>> my_audio_file.close()
With encoded False:
>>> from weaviate.util import file_encoder_b64 >>> encoded_audio = file_encoder_b64("my_audio_path.wav") >>> content = { ... 'audio': encoded_audio, ... 'certainty': 0.7 # or 'distance' instead ... } >>> query = client.query.aggregate('Audio')\ .with_fields('description')\ ... .with_near_audio(content, encode=False) # <- encode MUST be set to False
OR
>>> from weaviate.util import file_encoder_b64 >>> with open("my_audio_path.wav", "br") as my_audio_file: ... encoded_audio = file_encoder_b64(my_audio_file) >>> content = { ... 'audio': encoded_audio, ... 'certainty': 0.7 # or 'distance' instead ... } >>> query = client.query.aggregate('Audio')\ .with_fields('description')\ ... .with_near_audio(content, encode=False) # <- encode MUST be set to False
Encode Audio yourself:
>>> import base64 >>> with open("my_audio_path.wav", "br") as my_audio_file: ... encoded_audio = base64.b64encode(my_audio_file.read()).decode("utf-8") >>> content = { ... 'audio': encoded_audio, ... 'certainty': 0.7 # or 'distance' instead ... } >>> query = client.query.aggregate('Audio')\ .with_fields('description')\ ... .with_near_audio(content, encode=False) # <- encode MUST be set to False
Returns
- weaviate.gql.aggregate.AggregateBuilder
The updated AggregateBuilder.
Raises
- AttributeError
If another ‘near’ filter was already set.
- with_near_depth(content: dict, encode: bool = True) AggregateBuilder [source]
Set nearDepth filter.
Parameters
- contentdict
The content of the nearDepth filter to set. See examples below.
- encodebool, optional
Whether to encode the content[“depth”] to base64 and convert to string. If True, the content[“depth”] can be an depth path or a file opened in binary read mode. If False, the content[“depth”] MUST be a base64 encoded string (NOT bytes, i.e. NOT binary string that looks like this: b’BASE64ENCODED’ but simple ‘BASE64ENCODED’). By default True.
Examples
Content prototype:
>>> content = { ... 'depth': <str or binary read file>, ... # certainty ONLY with `cosine` distance specified in the schema ... 'certainty': <float>, # Optional, either 'certainty' OR 'distance' ... 'distance': <float>, # Optional, either 'certainty' OR 'distance' ... }
>>> { ... 'depth': "e5dc4a4c-ef0f-3aed-89a3-a73435c6bbcf", ... 'certainty': 0.7 # or 'distance' ... }
With encoded True:
>>> content = { ... 'depth': "my_depth_path.png", ... 'certainty': 0.7 # or 'distance' instead ... } >>> query = client.query.aggregate('Depth')\ .with_fields('description')\ ... .with_near_depth(content, encode=True) # <- encode MUST be set to True
OR
>>> my_depth_file = open("my_depth_path.png", "br") >>> content = { ... 'depth': my_depth_file, ... 'certainty': 0.7 # or 'distance' instead ... } >>> query = client.query.aggregate('Depth')\ .with_fields('description')\ ... .with_near_depth(content, encode=True) # <- encode MUST be set to True >>> my_depth_file.close()
With encoded False:
>>> from weaviate.util import file_encoder_b64 >>> encoded_depth = file_encoder_b64("my_depth_path.png") >>> content = { ... 'depth': encoded_depth, ... 'certainty': 0.7 # or 'distance' instead ... } >>> query = client.query.aggregate('Depth')\ .with_fields('description')\ ... .with_near_depth(content, encode=False) # <- encode MUST be set to False
OR
>>> from weaviate.util import file_encoder_b64 >>> with open("my_depth_path.png", "br") as my_depth_file: ... encoded_depth = file_encoder_b64(my_depth_file) >>> content = { ... 'depth': encoded_depth, ... 'certainty': 0.7 # or 'distance' instead ... } >>> query = client.query.aggregate('Depth')\ .with_fields('description')\ ... .with_near_depth(content, encode=False) # <- encode MUST be set to False
Encode Depth yourself:
>>> import base64 >>> with open("my_depth_path.png", "br") as my_depth_file: ... encoded_depth = base64.b64encode(my_depth_file.read()).decode("utf-8") >>> content = { ... 'depth': encoded_depth, ... 'certainty': 0.7 # or 'distance' instead ... } >>> query = client.query.aggregate('Depth')\ .with_fields('description')\ ... .with_near_depth(content, encode=False) # <- encode MUST be set to False
Returns
- weaviate.gql.aggregate.AggregateBuilder
The updated AggregateBuilder.
Raises
- AttributeError
If another ‘near’ filter was already set.
- with_near_image(content: dict, encode: bool = True) AggregateBuilder [source]
Set nearImage filter.
Parameters
- contentdict
The content of the nearImage filter to set. See examples below.
- encodebool, optional
Whether to encode the content[“image”] to base64 and convert to string. If True, the content[“image”] can be an image path or a file opened in binary read mode. If False, the content[“image”] MUST be a base64 encoded string (NOT bytes, i.e. NOT binary string that looks like this: b’BASE64ENCODED’ but simple ‘BASE64ENCODED’). By default True.
Examples
Content prototype:
>>> content = { ... 'image': <str or binary read file>, ... # certainty ONLY with `cosine` distance specified in the schema ... 'certainty': <float>, # Optional, either 'certainty' OR 'distance' ... 'distance': <float>, # Optional, either 'certainty' OR 'distance' ... }
>>> { ... 'image': "e5dc4a4c-ef0f-3aed-89a3-a73435c6bbcf", ... 'certainty': 0.7 # or 'distance' ... }
With encoded True:
>>> content = { ... 'image': "my_image_path.png", ... 'certainty': 0.7 # or 'distance' instead ... } >>> query = client.query.aggregate('Image')\ .with_fields('description')\ ... .with_near_image(content, encode=True) # <- encode MUST be set to True
OR
>>> my_image_file = open("my_image_path.png", "br") >>> content = { ... 'image': my_image_file, ... 'certainty': 0.7 # or 'distance' instead ... } >>> query = client.query.aggregate('Image')\ .with_fields('description')\ ... .with_near_image(content, encode=True) # <- encode MUST be set to True >>> my_image_file.close()
With encoded False:
>>> from weaviate.util import image_encoder_b64, image_decoder_b64 >>> encoded_image = image_encoder_b64("my_image_path.png") >>> content = { ... 'image': encoded_image, ... 'certainty': 0.7 # or 'distance' instead ... } >>> query = client.query.aggregate('Image')\ .with_fields('description')\ ... .with_near_image(content, encode=False) # <- encode MUST be set to False
OR
>>> from weaviate.util import image_encoder_b64, image_decoder_b64 >>> with open("my_image_path.png", "br") as my_image_file: ... encoded_image = image_encoder_b64(my_image_file) >>> content = { ... 'image': encoded_image, ... 'certainty': 0.7 # or 'distance' instead ... } >>> query = client.query.aggregate('Image')\ .with_fields('description')\ ... .with_near_image(content, encode=False) # <- encode MUST be set to False
Encode Image yourself:
>>> import base64 >>> with open("my_image_path.png", "br") as my_image_file: ... encoded_image = base64.b64encode(my_image_file.read()).decode("utf-8") >>> content = { ... 'image': encoded_image, ... 'certainty': 0.7 # or 'distance' instead ... } >>> query = client.query.aggregate('Image')\ .with_fields('description')\ ... .with_near_image(content, encode=False) # <- encode MUST be set to False
Returns
- weaviate.gql.aggregate.AggregateBuilder
The updated AggregateBuilder.
Raises
- AttributeError
If another ‘near’ filter was already set.
- with_near_imu(content: dict, encode: bool = True) AggregateBuilder [source]
Set nearIMU filter.
Parameters
- contentdict
The content of the nearIMU filter to set. See examples below.
- encodebool, optional
Whether to encode the content[“thermal”] to base64 and convert to string. If True, the content[“thermal”] can be an thermal path or a file opened in binary read mode. If False, the content[“thermal”] MUST be a base64 encoded string (NOT bytes, i.e. NOT binary string that looks like this: b’BASE64ENCODED’ but simple ‘BASE64ENCODED’). By default True.
Examples
Content prototype:
>>> content = { ... 'thermal': <str or binary read file>, ... # certainty ONLY with `cosine` distance specified in the schema ... 'certainty': <float>, # Optional, either 'certainty' OR 'distance' ... 'distance': <float>, # Optional, either 'certainty' OR 'distance' ... }
>>> { ... 'thermal': "e5dc4a4c-ef0f-3aed-89a3-a73435c6bbcf", ... 'certainty': 0.7 # or 'distance' ... }
With encoded True:
>>> content = { ... 'thermal': "my_thermal_path.png", ... 'certainty': 0.7 # or 'distance' instead ... } >>> query = client.query.aggregate('IMU')\ ... .with_fields('description')\ ... .with_near_thermal(content, encode=True) # <- encode MUST be set to True
OR
>>> my_thermal_file = open("my_thermal_path.png", "br") >>> content = { ... 'thermal': my_thermal_file, ... 'certainty': 0.7 # or 'distance' instead ... } >>> query = client.query.aggregate('IMU')\ ... .with_fields('description')\ ... .with_near_thermal(content, encode=True) # <- encode MUST be set to True >>> my_thermal_file.close()
With encoded False:
>>> from weaviate.util import file_encoder_b64 >>> encoded_thermal = file_encoder_b64("my_thermal_path.png") >>> content = { ... 'thermal': encoded_thermal, ... 'certainty': 0.7 # or 'distance' instead ... } >>> query = client.query.aggregate('IMU')\ ... .with_fields('description')\ ... .with_near_thermal(content, encode=False) # <- encode MUST be set to False
OR
>>> from weaviate.util import file_encoder_b64 >>> with open("my_thermal_path.png", "br") as my_thermal_file: ... encoded_thermal = file_encoder_b64(my_thermal_file) >>> content = { ... 'thermal': encoded_thermal, ... 'certainty': 0.7 # or 'distance' instead ... } >>> query = client.query.aggregate('IMU')\ ... .with_fields('description')\ ... .with_near_thermal(content, encode=False) # <- encode MUST be set to False
Encode IMU yourself:
>>> import base64 >>> with open("my_thermal_path.png", "br") as my_thermal_file: ... encoded_thermal = base64.b64encode(my_thermal_file.read()).decode("utf-8") >>> content = { ... 'thermal': encoded_thermal, ... 'certainty': 0.7 # or 'distance' instead ... } >>> query = client.query.aggregate('IMU')\ ... .with_fields('description')\ ... .with_near_thermal(content, encode=False) # <- encode MUST be set to False
Returns
- weaviate.gql.aggregate.AggregateBuilder
The updated AggregateBuilder.
Raises
- AttributeError
If another ‘near’ filter was already set.
- with_near_object(content: dict) AggregateBuilder [source]
Set nearObject filter.
Parameters
- contentdict
The content of the nearObject filter to set. See examples below.
Examples
Content prototype:
>>> content = { ... 'id': <str>, # OR 'beacon' ... 'beacon': <str>, # OR 'id' ... # certainty ONLY with `cosine` distance specified in the schema ... 'certainty': <float>, # Optional, either 'certainty' OR 'distance' ... 'distance': <float>, # Optional, either 'certainty' OR 'distance' ... }
>>> { ... 'id': "e5dc4a4c-ef0f-3aed-89a3-a73435c6bbcf", ... 'certainty': 0.7 # or 'distance' instead ... } >>> # alternatively >>> { ... 'beacon': "weaviate://localhost/Book/e5dc4a4c-ef0f-3aed-89a3-a73435c6bbcf" ... 'certainty': 0.7 # or 'distance' instead ... }
Returns
- weaviate.gql.aggregate.AggregateBuilder
Updated AggregateBuilder.
Raises
- AttributeError
If another ‘near’ filter was already set.
- with_near_text(content: dict) AggregateBuilder [source]
Set nearText filter. This filter can be used with text modules (text2vec). E.g.: text2vec-contextionary, text2vec-transformers. NOTE: The ‘autocorrect’ field is enabled only with the text-spellcheck Weaviate module.
Parameters
- contentdict
The content of the nearText filter to set. See examples below.
Examples
Content full prototype:
>>> content = { ... 'concepts': <list of str or str>, ... # certainty ONLY with `cosine` distance specified in the schema ... 'certainty': <float>, # Optional, either 'certainty' OR 'distance' ... 'distance': <float>, # Optional, either 'certainty' OR 'distance' ... 'moveAwayFrom': { # Optional ... 'concepts': <list of str or str>, ... 'force': <float> ... }, ... 'moveTo': { # Optional ... 'concepts': <list of str or str>, ... 'force': <float> ... }, ... 'autocorrect': <bool>, # Optional ... }
Full content:
>>> content = { ... 'concepts': ["fashion"], ... 'certainty': 0.7, # or 'distance' instead ... 'moveAwayFrom': { ... 'concepts': ["finance"], ... 'force': 0.45 ... }, ... 'moveTo': { ... 'concepts': ["haute couture"], ... 'force': 0.85 ... }, ... 'autocorrect': True ... }
Partial content:
>>> content = { ... 'concepts': ["fashion"], ... 'certainty': 0.7, # or 'distance' instead ... 'moveTo': { ... 'concepts': ["haute couture"], ... 'force': 0.85 ... } ... }
Minimal content:
>>> content = { ... 'concepts': "fashion" ... }
Returns
- weaviate.gql.aggregate.AggregateBuilder
Updated AggregateBuilder.
Raises
- AttributeError
If another ‘near’ filter was already set.
- with_near_thermal(content: dict, encode: bool = True) AggregateBuilder [source]
Set nearThermal filter.
Parameters
- contentdict
The content of the nearThermal filter to set. See examples below.
- encodebool, optional
Whether to encode the content[“thermal”] to base64 and convert to string. If True, the content[“thermal”] can be an thermal path or a file opened in binary read mode. If False, the content[“thermal”] MUST be a base64 encoded string (NOT bytes, i.e. NOT binary string that looks like this: b’BASE64ENCODED’ but simple ‘BASE64ENCODED’). By default True.
Examples
Content prototype:
>>> content = { ... 'thermal': <str or binary read file>, ... # certainty ONLY with `cosine` distance specified in the schema ... 'certainty': <float>, # Optional, either 'certainty' OR 'distance' ... 'distance': <float>, # Optional, either 'certainty' OR 'distance' ... }
>>> { ... 'thermal': "e5dc4a4c-ef0f-3aed-89a3-a73435c6bbcf", ... 'certainty': 0.7 # or 'distance' ... }
With encoded True:
>>> content = { ... 'thermal': "my_thermal_path.png", ... 'certainty': 0.7 # or 'distance' instead ... } >>> query = client.query.get('Thermal', 'description')\ ... .with_near_thermal(content, encode=True) # <- encode MUST be set to True
OR
>>> my_thermal_file = open("my_thermal_path.png", "br") >>> content = { ... 'thermal': my_thermal_file, ... 'certainty': 0.7 # or 'distance' instead ... } >>> query = client.query.aggregate('Thermal')\ ... .with_fields('description')\ ... .with_near_thermal(content, encode=True) # <- encode MUST be set to True >>> my_thermal_file.close()
With encoded False:
>>> from weaviate.util import file_encoder_b64 >>> encoded_thermal = file_encoder_b64("my_thermal_path.png") >>> content = { ... 'thermal': encoded_thermal, ... 'certainty': 0.7 # or 'distance' instead ... } >>> query = client.query.aggregate('Thermal')\ ... .with_fields('description')\ ... .with_near_thermal(content, encode=False) # <- encode MUST be set to False
OR
>>> from weaviate.util import file_encoder_b64 >>> with open("my_thermal_path.png", "br") as my_thermal_file: ... encoded_thermal = file_encoder_b64(my_thermal_file) >>> content = { ... 'thermal': encoded_thermal, ... 'certainty': 0.7 # or 'distance' instead ... } >>> query = client.query.aggregate('Thermal')\ ... .with_fields('description')\ ... .with_near_thermal(content, encode=False) # <- encode MUST be set to False
Encode Thermal yourself:
>>> import base64 >>> with open("my_thermal_path.png", "br") as my_thermal_file: ... encoded_thermal = base64.b64encode(my_thermal_file.read()).decode("utf-8") >>> content = { ... 'thermal': encoded_thermal, ... 'certainty': 0.7 # or 'distance' instead ... } >>> query = client.query.aggregate('Thermal')\ ... .with_fields('description')\ ... .with_near_thermal(content, encode=False) # <- encode MUST be set to False
Returns
- weaviate.gql.aggregate.AggregateBuilder
The updated AggregateBuilder.
Raises
- AttributeError
If another ‘near’ filter was already set.
- with_near_vector(content: dict) AggregateBuilder [source]
Set nearVector filter.
Parameters
- contentdict
The content of the nearVector filter to set. See examples below.
Examples
Content full prototype:
>>> content = { ... 'vector' : <list of float>, ... # certainty ONLY with `cosine` distance specified in the schema ... 'certainty': <float>, # Optional, either 'certainty' OR 'distance' ... 'distance': <float>, # Optional, either 'certainty' OR 'distance' ... }
- NOTE: Supported types for ‘vector’ are list, ‘numpy.ndarray`, torch.Tensor
and tf.Tensor.
Full content:
>>> content = { ... 'vector' : [.1, .2, .3, .5], ... 'certainty': 0.75, # or 'distance' instead ... }
Minimal content:
>>> content = { ... 'vector' : [.1, .2, .3, .5] ... }
Or
>>> content = { ... 'vector' : torch.tensor([.1, .2, .3, .5]) ... }
Or
>>> content = { ... 'vector' : torch.tensor([[.1, .2, .3, .5]]) # it is going to be squeezed. ... }
Returns
- weaviate.gql.aggregate.AggregateBuilder
Updated AggregateBuilder.
Raises
- AttributeError
If another ‘near’ filter was already set.
- with_near_video(content: dict, encode: bool = True) AggregateBuilder [source]
Set nearVideo filter.
Parameters
- contentdict
The content of the nearVideo filter to set. See examples below.
- encodebool, optional
Whether to encode the content[“video”] to base64 and convert to string. If True, the content[“video”] can be an video path or a file opened in binary read mode. If False, the content[“video”] MUST be a base64 encoded string (NOT bytes, i.e. NOT binary string that looks like this: b’BASE64ENCODED’ but simple ‘BASE64ENCODED’). By default True.
Examples
Content prototype:
>>> content = { ... 'video': <str or binary read file>, ... # certainty ONLY with `cosine` distance specified in the schema ... 'certainty': <float>, # Optional, either 'certainty' OR 'distance' ... 'distance': <float>, # Optional, either 'certainty' OR 'distance' ... }
>>> { ... 'video': "e5dc4a4c-ef0f-3aed-89a3-a73435c6bbcf", ... 'certainty': 0.7 # or 'distance' ... }
With encoded True:
>>> content = { ... 'video': "my_video_path.avi", ... 'certainty': 0.7 # or 'distance' instead ... } >>> query = client.query.aggregate('Video')\ .with_fields('description')\ ... .with_near_video(content, encode=True) # <- encode MUST be set to True
OR
>>> my_video_file = open("my_video_path.avi", "br") >>> content = { ... 'video': my_video_file, ... 'certainty': 0.7 # or 'distance' instead ... } >>> query = client.query.aggregate('Video')\ .with_fields('description')\ ... .with_near_video(content, encode=True) # <- encode MUST be set to True >>> my_video_file.close()
With encoded False:
>>> from weaviate.util import file_encoder_b64 >>> encoded_video = file_encoder_b64("my_video_path.avi") >>> content = { ... 'video': encoded_video, ... 'certainty': 0.7 # or 'distance' instead ... } >>> query = client.query.aggregate('Video')\ .with_fields('description')\ ... .with_near_video(content, encode=False) # <- encode MUST be set to False
OR
>>> from weaviate.util import file_encoder_b64, video_decoder_b64 >>> with open("my_video_path.avi", "br") as my_video_file: ... encoded_video = file_encoder_b64(my_video_file) >>> content = { ... 'video': encoded_video, ... 'certainty': 0.7 # or 'distance' instead ... } >>> query = client.query.aggregate('Video')\ .with_fields('description')\ ... .with_near_video(content, encode=False) # <- encode MUST be set to False
Encode Video yourself:
>>> import base64 >>> with open("my_video_path.avi", "br") as my_video_file: ... encoded_video = base64.b64encode(my_video_file.read()).decode("utf-8") >>> content = { ... 'video': encoded_video, ... 'certainty': 0.7 # or 'distance' instead ... } >>> query = client.query.aggregate('Video')\ .with_fields('description')\ ... .with_near_video(content, encode=False) # <- encode MUST be set to False
Returns
- weaviate.gql.aggregate.AggregateBuilder
The updated AggregateBuilder.
Raises
- AttributeError
If another ‘near’ filter was already set.
- with_object_limit(limit: int) AggregateBuilder [source]
Set objectLimit to limit vector search results used within the aggregation query only when with near<MEDIA> filter.
Parameters
- limitint
The object limit.
Returns
- weaviate.gql.aggregate.AggregateBuilder
Updated AggregateBuilder.
- with_tenant(tenant: str) AggregateBuilder [source]
Sets a tenant for the query.
- with_where(content: dict) AggregateBuilder [source]
Set ‘where’ filter.
Parameters
- contentdict
The where filter to include in the aggregate query. See examples below.
Examples
The content prototype is like this:
>>> content = { ... 'operator': '<operator>', ... 'operands': [ ... { ... 'path': [path], ... 'operator': '<operator>' ... '<valueType>': <value> ... }, ... { ... 'path': [<matchPath>], ... 'operator': '<operator>', ... '<valueType>': <value> ... } ... ] ... }
This is a complete where filter but it does not have to be like this all the time.
Single operand:
>>> content = { ... 'path': ["wordCount"], # Path to the property that should be used ... 'operator': 'GreaterThan', # operator ... 'valueInt': 1000 # value (which is always = to the type of the path property) ... }
Or
>>> content = { ... 'path': ["id"], ... 'operator': 'Equal', ... 'valueString': "e5dc4a4c-ef0f-3aed-89a3-a73435c6bbcf" ... }
Multiple operands:
>>> content = { ... 'operator': 'And', ... 'operands': [ ... { ... 'path': ["wordCount"], ... 'operator': 'GreaterThan', ... 'valueInt': 1000 ... }, ... { ... 'path': ["wordCount"], ... 'operator': 'LessThan', ... 'valueInt': 1500 ... } ... ] ... }
Returns
- weaviate.gql.aggregate.AggregateBuilder
Updated AggregateBuilder.
weaviate.gql.filter module
GraphQL filters for Get and Aggregate commands. GraphQL abstract class for GraphQL commands to inherit from.
- class weaviate.gql.filter.Ask(content: dict)[source]
Bases:
Filter
Ask class used to filter weaviate objects by asking a question.
Initialize a Ask class instance.
Parameters
- contentlist
The content of the ask clause.
Raises
- TypeError
If ‘content’ is not of type dict.
- ValueError
If ‘content’ has key “certainty”/”distance” but the value is not float.
- TypeError
If ‘content’ has key “properties” but the type is not list or str.
- class weaviate.gql.filter.Filter(content: dict)[source]
Bases:
ABC
A base abstract class for all filters.
Initialize a Filter class instance.
Parameters
- contentdict
The content of the Filter clause.
- property content: dict
- class weaviate.gql.filter.GraphQL(connection: Connection | ConnectionV4)[source]
Bases:
ABC
A base abstract class for GraphQL commands, such as Get, Aggregate.
Initialize a GraphQL abstract class instance.
Parameters
- connectionweaviate.connect.Connection
Connection object to an active and running weaviate instance.
- class weaviate.gql.filter.MediaType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]
Bases:
Enum
- AUDIO = 'audio'
- DEPTH = 'depth'
- IMAGE = 'image'
- IMU = 'imu'
- THERMAL = 'thermal'
- VIDEO = 'video'
- class weaviate.gql.filter.NearAudio(content: dict)[source]
Bases:
NearMedia
NearAudio class used to filter weaviate objects.
Initialize a NearAudio class instance.
Parameters
- contentlist
The content of the nearAudio clause.
Raises
- TypeError
If ‘content’ is not of type dict.
- TypeError
If ‘content[“audio”]’ is not of type str.
- ValueError
If ‘content’ has key “certainty”/”distance” but the value is not float.
- class weaviate.gql.filter.NearDepth(content: dict)[source]
Bases:
NearMedia
NearDepth class used to filter weaviate objects.
Initialize a NearDepth class instance.
Parameters
- contentlist
The content of the nearDepth clause.
Raises
- TypeError
If ‘content’ is not of type dict.
- TypeError
If ‘content[“depth”]’ is not of type str.
- ValueError
If ‘content’ has key “certainty”/”distance” but the value is not float.
- class weaviate.gql.filter.NearIMU(content: dict)[source]
Bases:
NearMedia
NearIMU class used to filter weaviate objects.
Initialize a NearIMU class instance.
Parameters
- contentlist
The content of the nearIMU clause.
Raises
- TypeError
If ‘content’ is not of type dict.
- TypeError
If ‘content[“imu”]’ is not of type str.
- ValueError
If ‘content’ has key “certainty”/”distance” but the value is not float.
- class weaviate.gql.filter.NearImage(content: dict)[source]
Bases:
NearMedia
NearImage class used to filter weaviate objects.
Initialize a NearImage class instance.
Parameters
- contentlist
The content of the nearImage clause.
Raises
- TypeError
If ‘content’ is not of type dict.
- TypeError
If ‘content[“image”]’ is not of type str.
- ValueError
If ‘content’ has key “certainty”/”distance” but the value is not float.
- class weaviate.gql.filter.NearMedia(content: dict, media_type: MediaType)[source]
Bases:
Filter
Initialize a NearMedia class instance.
Parameters
- contentlist
The content of the near<Media> clause.
Raises
- TypeError
If ‘content’ is not of type dict.
- TypeError
If ‘content[“<media>”]’ is not of type str.
- ValueError
If ‘content’ has key “certainty”/”distance” but the value is not float.
- class weaviate.gql.filter.NearObject(content: dict, is_server_version_14: bool)[source]
Bases:
Filter
NearObject class used to filter weaviate objects.
Initialize a NearVector class instance.
Parameters
- contentlist
The content of the nearVector clause.
- is_server_version_14bool
Whether the Server version is >= 1.14.0.
Raises
- TypeError
If ‘content’ is not of type dict.
- ValueError
If ‘content’ has key “certainty”/”distance” but the value is not float.
- TypeError
If ‘id’/’beacon’ key does not have a value of type str!
- class weaviate.gql.filter.NearText(content: dict)[source]
Bases:
Filter
NearText class used to filter weaviate objects. Can be used with text models only (text2vec). E.g.: text2vec-contextionary, text2vec-transformers.
Initialize a NearText class instance.
Parameters
- contentdict
The content of the nearText clause.
Raises
- TypeError
If ‘content’ is not of type dict.
- ValueError
If ‘content’ has key “certainty”/”distance” but the value is not float.
- class weaviate.gql.filter.NearThermal(content: dict)[source]
Bases:
NearMedia
NearThermal class used to filter weaviate objects.
Initialize a NearThermal class instance.
Parameters
- contentlist
The content of the nearThermal clause.
Raises
- TypeError
If ‘content’ is not of type dict.
- TypeError
If ‘content[“thermal”]’ is not of type str.
- ValueError
If ‘content’ has key “certainty”/”distance” but the value is not float.
- class weaviate.gql.filter.NearVector(content: dict)[source]
Bases:
Filter
NearVector class used to filter weaviate objects.
Initialize a NearVector class instance.
Parameters
- contentlist
The content of the nearVector clause.
Raises
- TypeError
If ‘content’ is not of type dict.
- KeyError
If ‘content’ does not contain “vector”.
- TypeError
If ‘content[“vector”]’ is not of type list.
- AttributeError
If invalid ‘content’ keys are provided.
- ValueError
If ‘content’ has key “certainty”/”distance” but the value is not float.
- class weaviate.gql.filter.NearVideo(content: dict)[source]
Bases:
NearMedia
NearVideo class used to filter weaviate objects.
Initialize a NearVideo class instance.
Parameters
- contentlist
The content of the nearVideo clause.
Raises
- TypeError
If ‘content’ is not of type dict.
- TypeError
If ‘content[“video”]’ is not of type str.
- ValueError
If ‘content’ has key “certainty”/”distance” but the value is not float.
- class weaviate.gql.filter.Sort(content: dict | list)[source]
Bases:
Filter
Sort filter class used to sort weaviate objects.
Initialize a Where filter class instance.
Parameters
- contentlist or dict
The content of the sort filter clause or a single clause.
Raises
- TypeError
If ‘content’ is not of type dict.
- ValueError
If a mandatory key is missing in the filter content.
- add(content: dict | list) None [source]
Add more sort clauses to the already existing sort clauses.
Parameters
- contentlist or dict
The content of the sort filter clause or a single clause to be added to the already existing ones.
Raises
- TypeError
If ‘content’ is not of type dict.
- ValueError
If a mandatory key is missing in the filter content.
- class weaviate.gql.filter.Where(content: dict)[source]
Bases:
Filter
Where filter class used to filter weaviate objects.
Initialize a Where filter class instance.
Parameters
- contentdict
The content of the where filter clause.
Raises
- TypeError
If ‘content’ is not of type dict.
- ValueError
If a mandatory key is missing in the filter content.
weaviate.gql.get module
GraphQL Get command.
- class weaviate.gql.get.AdditionalProperties(uuid: bool = False, vector: bool = False, creationTimeUnix: bool = False, lastUpdateTimeUnix: bool = False, distance: bool = False, certainty: bool = False, score: bool = False, explainScore: bool = False)[source]
Bases:
object
- certainty: bool = False
- creationTimeUnix: bool = False
- distance: bool = False
- explainScore: bool = False
- lastUpdateTimeUnix: bool = False
- score: bool = False
- uuid: bool = False
- vector: bool = False
- class weaviate.gql.get.BM25(query: str, properties: List[str] | None)[source]
Bases:
object
- properties: List[str] | None
- query: str
- class weaviate.gql.get.GetBuilder(class_name: str, properties: Sequence[str | LinkTo] | str | None, connection: Connection)[source]
Bases:
GraphQL
GetBuilder class used to create GraphQL queries.
Initialize a GetBuilder class instance.
Parameters
- class_namestr
Class name of the objects to interact with.
- propertiesstr or list of str
Properties of the objects to interact with.
- connectionweaviate.connect.Connection
Connection object to an active and running Weaviate instance.
Raises
- TypeError
If argument/s is/are of wrong type.
- build(wrap_get: bool = True) str [source]
Build query filter as a string.
Parameters
- wrap_get: bool
A boolean to decide wether {Get{…}} is placed around the query. Useful for multi_get.
Returns
- str
The GraphQL query as a string.
- do() dict [source]
Builds and runs the query.
Returns
- dict
The response of the query.
Raises
- requests.ConnectionError
If the network connection to weaviate fails.
- weaviate.UnexpectedStatusCodeException
If weaviate reports a none OK status.
- property name: str
- with_additional(properties: List | str | Dict[str, str | List[str]] | Tuple[dict, dict] | AdditionalProperties) GetBuilder [source]
Add additional properties (i.e. properties from _additional clause). See Examples below. If the the ‘properties’ is of data type str or list of str then the method is idempotent, if it is of type dict or tuple then the exiting property is going to be replaced. To set the setting of one of the additional property use the tuple data type where properties look like this (clause: dict, settings: dict) where the ‘settings’ are the properties inside the ‘(…)’ of the clause. See Examples for more information.
Parameters
- propertiesstr, list of str, dict[str, str], dict[str, list of str] or tuple[dict, dict]
The additional properties to include in the query. Can be property name as str, a list of property names, a dictionary (clause without settings) where the value is a str or list of str, or a tuple of 2 elements:
(clause: Dict[str, str or list[str]], settings: Dict[str, Any])
where the ‘clause’ is the property and all its sub-properties and the ‘settings’ is the setting of the property, i.e. everything that is inside the (…) right after the property name. See Examples below.
Examples
>>> # single additional property with this GraphQL query >>> ''' ... { ... Get { ... Article { ... title ... author ... _additional { ... id ... } ... } ... } ... } ... ''' >>> client.query\ ... .get('Article', ['title', 'author'])\ ... .with_additional('id']) # argument as `str`
>>> # multiple additional property with this GraphQL query >>> ''' ... { ... Get { ... Article { ... title ... author ... _additional { ... id ... certainty ... } ... } ... } ... } ... ''' >>> client.query\ ... .get('Article', ['title', 'author'])\ ... .with_additional(['id', 'certainty']) # argument as `List[str]`
>>> # additional properties as clause with this GraphQL query >>> ''' ... { ... Get { ... Article { ... title ... author ... _additional { ... classification { ... basedOn ... classifiedFields ... completed ... id ... scope ... } ... } ... } ... } ... } ... ''' >>> client.query\ ... .get('Article', ['title', 'author'])\ ... .with_additional( ... { ... 'classification' : ['basedOn', 'classifiedFields', 'completed', 'id'] ... } ... ) # argument as `dict[str, List[str]]` >>> # or with this GraphQL query >>> ''' ... { ... Get { ... Article { ... title ... author ... _additional { ... classification { ... completed ... } ... } ... } ... } ... } ... ''' >>> client.query\ ... .get('Article', ['title', 'author'])\ ... .with_additional( ... { ... 'classification' : 'completed' ... } ... ) # argument as `Dict[str, str]`
Consider the following GraphQL clause:
>>> ''' ... { ... Get { ... Article { ... title ... author ... _additional { ... token ( ... properties: ["content"] ... limit: 10 ... certainty: 0.8 ... ) { ... certainty ... endPosition ... entity ... property ... startPosition ... word ... } ... } ... } ... } ... } ... '''
Then the python translation of this is the following:
>>> clause = { ... 'token': [ # if only one, can be passes as `str` ... 'certainty', ... 'endPosition', ... 'entity', ... 'property', ... 'startPosition', ... 'word', ... ] ... } >>> settings = { ... 'properties': ["content"], # is required ... 'limit': 10, # optional, int ... 'certainty': 0.8 # optional, float ... } >>> client.query\ ... .get('Article', ['title', 'author'])\ ... .with_additional( ... (clause, settings) ... ) # argument as `Tuple[Dict[str, List[str]], Dict[str, Any]]`
If the desired clause does not match any example above, then the clause can always be converted to string before passing it to the .with_additional() method.
Returns
- weaviate.gql.get.GetBuilder
The updated GetBuilder.
Raises
- TypeError
If one of the property is not of a correct data type.
- with_after(after_uuid: str | UUID) GetBuilder [source]
Can be used to extract all elements by giving the last ID from the previous “page”.
Requires limit to be set but cannot be combined with any other filters or search. Part of the Cursor API.
- with_alias(alias: str) GetBuilder [source]
Gives an alias for the query. Needs to be used if ‘multi_get’ requests the same ‘class_name’ twice.
Parameters
- alias: str
The alias for the query.
- with_ask(content: dict) GetBuilder [source]
Ask a question for which weaviate will retrieve the answer from your data. This filter can be used only with QnA module: qna-transformers. NOTE: The ‘autocorrect’ field is enabled only with the text-spellcheck Weaviate module.
Parameters
- contentdict
The content of the ask filter to set. See examples below.
Examples
Content full prototype:
>>> content = { ... 'question' : <str>, ... # certainty ONLY with `cosine` distance specified in the schema ... 'certainty': <float>, # Optional, either 'certainty' OR 'distance' ... 'distance': <float>, # Optional, either 'certainty' OR 'distance' ... 'properties': <list of str or str> # Optional ... 'autocorrect': <bool>, # Optional ... }
Full content:
>>> content = { ... 'question' : "What is the NLP?", ... 'certainty': 0.7, # or 'distance' ... 'properties': ['body'] # search the answer in these properties only. ... 'autocorrect': True ... }
Minimal content:
>>> content = { ... 'question' : "What is the NLP?" ... }
Returns
- weaviate.gql.get.GetBuilder
The updated GetBuilder.
- with_autocut(autocut: int) GetBuilder [source]
Cuts off irrelevant results based on “jumps” in scores.
- with_bm25(query: str, properties: List[str] | None = None) GetBuilder [source]
Add BM25 query to search the inverted index for keywords.
Parameters
- query: str
The query to search for.
- properties: Optional[List[str]]
Which properties should be searched. If ‘None’ or empty all properties will be searched. By default, None
- with_consistency_level(consistency_level: ConsistencyLevel) GetBuilder [source]
Set the consistency level for the request.
- with_generate(single_prompt: str | None = None, grouped_task: str | None = None, grouped_properties: List[str] | None = None) GetBuilder [source]
Generate responses using the OpenAI generative search.
At least one of the two parameters must be set.
Parameters
- grouped_task: Optional[str]
The task to generate a grouped response.
- grouped_properties: Optional[List[str]]:
The properties whose contents are added to the prompts. If None or empty, all text properties contents are added.
- single_prompt: Optional[str]
The prompt to generate a single response.
- with_group_by(properties: List[str], groups: int, objects_per_group: int) GetBuilder [source]
Retrieve groups of objects from Weaviate.
Note that the return values must be set using .with_additional() to see the output.
Parameters
- properties: List[str]
Properties to group by
- groups: int
Maximum number of groups
- objects_per_group: int
Maximum number of objects per group
- with_hybrid(query: str, alpha: float | None = None, vector: List[float] | None = None, properties: List[str] | None = None, fusion_type: HybridFusion | None = None) GetBuilder [source]
Get objects using bm25 and vector, then combine the results using a reciprocal ranking algorithm.
Parameters
- query: str
The query to search for.
- alpha: Optional[float]
Factor determining how BM25 and vector search are weighted. If ‘None’ the weaviate default of 0.75 is used. By default, None alpha = 0 -> bm25, alpha=1 -> vector search
- vector: Optional[List[float]]
Vector that is searched for. If ‘None’, weaviate will use the configured text-to-vector module to create a vector from the “query” field. By default, None
- properties: Optional[List[str]]:
Which properties should be searched by BM25. Does not have any effect for vector search. If None or empty all properties are searched.
- fusion_type: Optional[HybridFusionType]:
Which fusion type should be used to merge keyword and vector search.
- with_limit(limit: int) GetBuilder [source]
The limit of objects returned.
Parameters
- limitint
The max number of objects returned.
Returns
- weaviate.gql.get.GetBuilder
The updated GetBuilder.
Raises
- ValueError
If ‘limit’ is non-positive.
- with_near_audio(content: dict, encode: bool = True) GetBuilder [source]
Set nearAudio filter.
Parameters
- contentdict
The content of the nearAudio filter to set. See examples below.
- encodebool, optional
Whether to encode the content[“audio”] to base64 and convert to string. If True, the content[“audio”] can be an audio path or a file opened in binary read mode. If False, the content[“audio”] MUST be a base64 encoded string (NOT bytes, i.e. NOT binary string that looks like this: b’BASE64ENCODED’ but simple ‘BASE64ENCODED’). By default True.
Examples
Content prototype:
>>> content = { ... 'audio': <str or binary read file>, ... # certainty ONLY with `cosine` distance specified in the schema ... 'certainty': <float>, # Optional, either 'certainty' OR 'distance' ... 'distance': <float>, # Optional, either 'certainty' OR 'distance' ... }
>>> { ... 'audio': "e5dc4a4c-ef0f-3aed-89a3-a73435c6bbcf", ... 'certainty': 0.7 # or 'distance' ... }
With encoded True:
>>> content = { ... 'audio': "my_audio_path.wav", ... 'certainty': 0.7 # or 'distance' instead ... } >>> query = client.query.get('Audio', 'description')\ ... .with_near_audio(content, encode=True) # <- encode MUST be set to True
OR
>>> my_audio_file = open("my_audio_path.wav", "br") >>> content = { ... 'audio': my_audio_file, ... 'certainty': 0.7 # or 'distance' instead ... } >>> query = client.query.get('Audio', 'description')\ ... .with_near_audio(content, encode=True) # <- encode MUST be set to True >>> my_audio_file.close()
With encoded False:
>>> from weaviate.util import file_encoder_b64 >>> encoded_audio = file_encoder_b64("my_audio_path.wav") >>> content = { ... 'audio': encoded_audio, ... 'certainty': 0.7 # or 'distance' instead ... } >>> query = client.query.get('Audio', 'description')\ ... .with_near_audio(content, encode=False) # <- encode MUST be set to False
OR
>>> from weaviate.util import file_encoder_b64 >>> with open("my_audio_path.wav", "br") as my_audio_file: ... encoded_audio = file_encoder_b64(my_audio_file) >>> content = { ... 'audio': encoded_audio, ... 'certainty': 0.7 # or 'distance' instead ... } >>> query = client.query.get('Audio', 'description')\ ... .with_near_audio(content, encode=False) # <- encode MUST be set to False
Encode Audio yourself:
>>> import base64 >>> with open("my_audio_path.wav", "br") as my_audio_file: ... encoded_audio = base64.b64encode(my_audio_file.read()).decode("utf-8") >>> content = { ... 'audio': encoded_audio, ... 'certainty': 0.7 # or 'distance' instead ... } >>> query = client.query.get('Audio', 'description')\ ... .with_near_audio(content, encode=False) # <- encode MUST be set to False
Returns
- weaviate.gql.get.GetBuilder
The updated GetBuilder.
Raises
- AttributeError
If another ‘near’ filter was already set.
- with_near_depth(content: dict, encode: bool = True) GetBuilder [source]
Set nearDepth filter.
Parameters
- contentdict
The content of the nearDepth filter to set. See examples below.
- encodebool, optional
Whether to encode the content[“depth”] to base64 and convert to string. If True, the content[“depth”] can be an depth path or a file opened in binary read mode. If False, the content[“depth”] MUST be a base64 encoded string (NOT bytes, i.e. NOT binary string that looks like this: b’BASE64ENCODED’ but simple ‘BASE64ENCODED’). By default True.
Examples
Content prototype:
>>> content = { ... 'depth': <str or binary read file>, ... # certainty ONLY with `cosine` distance specified in the schema ... 'certainty': <float>, # Optional, either 'certainty' OR 'distance' ... 'distance': <float>, # Optional, either 'certainty' OR 'distance' ... }
>>> { ... 'depth': "e5dc4a4c-ef0f-3aed-89a3-a73435c6bbcf", ... 'certainty': 0.7 # or 'distance' ... }
With encoded True:
>>> content = { ... 'depth': "my_depth_path.png", ... 'certainty': 0.7 # or 'distance' instead ... } >>> query = client.query.get('Depth', 'description')\ ... .with_near_depth(content, encode=True) # <- encode MUST be set to True
OR
>>> my_depth_file = open("my_depth_path.png", "br") >>> content = { ... 'depth': my_depth_file, ... 'certainty': 0.7 # or 'distance' instead ... } >>> query = client.query.get('Depth', 'description')\ ... .with_near_depth(content, encode=True) # <- encode MUST be set to True >>> my_depth_file.close()
With encoded False:
>>> from weaviate.util import file_encoder_b64 >>> encoded_depth = file_encoder_b64("my_depth_path.png") >>> content = { ... 'depth': encoded_depth, ... 'certainty': 0.7 # or 'distance' instead ... } >>> query = client.query.get('Depth', 'description')\ ... .with_near_depth(content, encode=False) # <- encode MUST be set to False
OR
>>> from weaviate.util import file_encoder_b64 >>> with open("my_depth_path.png", "br") as my_depth_file: ... encoded_depth = file_encoder_b64(my_depth_file) >>> content = { ... 'depth': encoded_depth, ... 'certainty': 0.7 # or 'distance' instead ... } >>> query = client.query.get('Depth', 'description')\ ... .with_near_depth(content, encode=False) # <- encode MUST be set to False
Encode Depth yourself:
>>> import base64 >>> with open("my_depth_path.png", "br") as my_depth_file: ... encoded_depth = base64.b64encode(my_depth_file.read()).decode("utf-8") >>> content = { ... 'depth': encoded_depth, ... 'certainty': 0.7 # or 'distance' instead ... } >>> query = client.query.get('Depth', 'description')\ ... .with_near_depth(content, encode=False) # <- encode MUST be set to False
Returns
- weaviate.gql.get.GetBuilder
The updated GetBuilder.
Raises
- AttributeError
If another ‘near’ filter was already set.
- with_near_image(content: dict, encode: bool = True) GetBuilder [source]
Set nearImage filter.
Parameters
- contentdict
The content of the nearImage filter to set. See examples below.
- encodebool, optional
Whether to encode the content[“image”] to base64 and convert to string. If True, the content[“image”] can be an image path or a file opened in binary read mode. If False, the content[“image”] MUST be a base64 encoded string (NOT bytes, i.e. NOT binary string that looks like this: b’BASE64ENCODED’ but simple ‘BASE64ENCODED’). By default True.
Examples
Content prototype:
>>> content = { ... 'image': <str or binary read file>, ... # certainty ONLY with `cosine` distance specified in the schema ... 'certainty': <float>, # Optional, either 'certainty' OR 'distance' ... 'distance': <float>, # Optional, either 'certainty' OR 'distance' ... }
>>> { ... 'image': "e5dc4a4c-ef0f-3aed-89a3-a73435c6bbcf", ... 'certainty': 0.7 # or 'distance' ... }
With encoded True:
>>> content = { ... 'image': "my_image_path.png", ... 'certainty': 0.7 # or 'distance' instead ... } >>> query = client.query.get('Image', 'description')\ ... .with_near_image(content, encode=True) # <- encode MUST be set to True
OR
>>> my_image_file = open("my_image_path.png", "br") >>> content = { ... 'image': my_image_file, ... 'certainty': 0.7 # or 'distance' instead ... } >>> query = client.query.get('Image', 'description')\ ... .with_near_image(content, encode=True) # <- encode MUST be set to True >>> my_image_file.close()
With encoded False:
>>> from weaviate.util import image_encoder_b64, image_decoder_b64 >>> encoded_image = image_encoder_b64("my_image_path.png") >>> content = { ... 'image': encoded_image, ... 'certainty': 0.7 # or 'distance' instead ... } >>> query = client.query.get('Image', 'description')\ ... .with_near_image(content, encode=False) # <- encode MUST be set to False
OR
>>> from weaviate.util import image_encoder_b64, image_decoder_b64 >>> with open("my_image_path.png", "br") as my_image_file: ... encoded_image = image_encoder_b64(my_image_file) >>> content = { ... 'image': encoded_image, ... 'certainty': 0.7 # or 'distance' instead ... } >>> query = client.query.get('Image', 'description')\ ... .with_near_image(content, encode=False) # <- encode MUST be set to False
Encode Image yourself:
>>> import base64 >>> with open("my_image_path.png", "br") as my_image_file: ... encoded_image = base64.b64encode(my_image_file.read()).decode("utf-8") >>> content = { ... 'image': encoded_image, ... 'certainty': 0.7 # or 'distance' instead ... } >>> query = client.query.get('Image', 'description')\ ... .with_near_image(content, encode=False) # <- encode MUST be set to False
Returns
- weaviate.gql.get.GetBuilder
The updated GetBuilder.
Raises
- AttributeError
If another ‘near’ filter was already set.
- with_near_imu(content: dict, encode: bool = True) GetBuilder [source]
Set nearIMU filter.
Parameters
- contentdict
The content of the nearIMU filter to set. See examples below.
- encodebool, optional
Whether to encode the content[“thermal”] to base64 and convert to string. If True, the content[“thermal”] can be an thermal path or a file opened in binary read mode. If False, the content[“thermal”] MUST be a base64 encoded string (NOT bytes, i.e. NOT binary string that looks like this: b’BASE64ENCODED’ but simple ‘BASE64ENCODED’). By default True.
Examples
Content prototype:
>>> content = { ... 'thermal': <str or binary read file>, ... # certainty ONLY with `cosine` distance specified in the schema ... 'certainty': <float>, # Optional, either 'certainty' OR 'distance' ... 'distance': <float>, # Optional, either 'certainty' OR 'distance' ... }
>>> { ... 'thermal': "e5dc4a4c-ef0f-3aed-89a3-a73435c6bbcf", ... 'certainty': 0.7 # or 'distance' ... }
With encoded True:
>>> content = { ... 'thermal': "my_thermal_path.png", ... 'certainty': 0.7 # or 'distance' instead ... } >>> query = client.query.get('IMU', 'description')\ ... .with_near_thermal(content, encode=True) # <- encode MUST be set to True
OR
>>> my_thermal_file = open("my_thermal_path.png", "br") >>> content = { ... 'thermal': my_thermal_file, ... 'certainty': 0.7 # or 'distance' instead ... } >>> query = client.query.get('IMU', 'description')\ ... .with_near_thermal(content, encode=True) # <- encode MUST be set to True >>> my_thermal_file.close()
With encoded False:
>>> from weaviate.util import file_encoder_b64 >>> encoded_thermal = file_encoder_b64("my_thermal_path.png") >>> content = { ... 'thermal': encoded_thermal, ... 'certainty': 0.7 # or 'distance' instead ... } >>> query = client.query.get('IMU', 'description')\ ... .with_near_thermal(content, encode=False) # <- encode MUST be set to False
OR
>>> from weaviate.util import file_encoder_b64 >>> with open("my_thermal_path.png", "br") as my_thermal_file: ... encoded_thermal = file_encoder_b64(my_thermal_file) >>> content = { ... 'thermal': encoded_thermal, ... 'certainty': 0.7 # or 'distance' instead ... } >>> query = client.query.get('IMU', 'description')\ ... .with_near_thermal(content, encode=False) # <- encode MUST be set to False
Encode IMU yourself:
>>> import base64 >>> with open("my_thermal_path.png", "br") as my_thermal_file: ... encoded_thermal = base64.b64encode(my_thermal_file.read()).decode("utf-8") >>> content = { ... 'thermal': encoded_thermal, ... 'certainty': 0.7 # or 'distance' instead ... } >>> query = client.query.get('IMU', 'description')\ ... .with_near_thermal(content, encode=False) # <- encode MUST be set to False
Returns
- weaviate.gql.get.GetBuilder
The updated GetBuilder.
Raises
- AttributeError
If another ‘near’ filter was already set.
- with_near_object(content: dict) GetBuilder [source]
Set nearObject filter.
Parameters
- contentdict
The content of the nearObject filter to set. See examples below.
Examples
Content prototype:
>>> { ... 'id': "e5dc4a4c-ef0f-3aed-89a3-a73435c6bbcf", ... # certainty ONLY with `cosine` distance specified in the schema ... 'certainty': <float>, # Optional, either 'certainty' OR 'distance' ... 'distance': <float>, # Optional, either 'certainty' OR 'distance' ... } >>> # alternatively >>> { ... 'beacon': "weaviate://localhost/ClassName/e5dc4a4c-ef0f-3aed-89a3-a73435c6bbcf" ... # certainty ONLY with `cosine` distance specified in the schema ... 'certainty': <float>, # Optional, either 'certainty' OR 'distance' ... 'distance': <float>, # Optional, either 'certainty' OR 'distance' ... }
Returns
- weaviate.gql.get.GetBuilder
The updated GetBuilder.
Raises
- AttributeError
If another ‘near’ filter was already set.
- with_near_text(content: dict) GetBuilder [source]
Set nearText filter. This filter can be used with text modules (text2vec). E.g.: text2vec-contextionary, text2vec-transformers. NOTE: The ‘autocorrect’ field is enabled only with the text-spellcheck Weaviate module.
Parameters
- contentdict
The content of the nearText filter to set. See examples below.
Examples
Content full prototype:
>>> content = { ... 'concepts': <list of str or str>, ... # certainty ONLY with `cosine` distance specified in the schema ... 'certainty': <float>, # Optional, either 'certainty' OR 'distance' ... 'distance': <float>, # Optional, either 'certainty' OR 'distance' ... 'moveAwayFrom': { # Optional ... 'concepts': <list of str or str>, ... 'force': <float> ... }, ... 'moveTo': { # Optional ... 'concepts': <list of str or str>, ... 'force': <float> ... }, ... 'autocorrect': <bool>, # Optional ... }
Full content:
>>> content = { ... 'concepts': ["fashion"], ... 'certainty': 0.7, # or 'distance' ... 'moveAwayFrom': { ... 'concepts': ["finance"], ... 'force': 0.45 ... }, ... 'moveTo': { ... 'concepts': ["haute couture"], ... 'force': 0.85 ... }, ... 'autocorrect': True ... }
Partial content:
>>> content = { ... 'concepts': ["fashion"], ... 'certainty': 0.7, # or 'distance' ... 'moveTo': { ... 'concepts': ["haute couture"], ... 'force': 0.85 ... } ... }
Minimal content:
>>> content = { ... 'concepts': "fashion" ... }
Returns
- weaviate.gql.get.GetBuilder
The updated GetBuilder.
Raises
- AttributeError
If another ‘near’ filter was already set.
- with_near_thermal(content: dict, encode: bool = True) GetBuilder [source]
Set nearThermal filter.
Parameters
- contentdict
The content of the nearThermal filter to set. See examples below.
- encodebool, optional
Whether to encode the content[“thermal”] to base64 and convert to string. If True, the content[“thermal”] can be an thermal path or a file opened in binary read mode. If False, the content[“thermal”] MUST be a base64 encoded string (NOT bytes, i.e. NOT binary string that looks like this: b’BASE64ENCODED’ but simple ‘BASE64ENCODED’). By default True.
Examples
Content prototype:
>>> content = { ... 'thermal': <str or binary read file>, ... # certainty ONLY with `cosine` distance specified in the schema ... 'certainty': <float>, # Optional, either 'certainty' OR 'distance' ... 'distance': <float>, # Optional, either 'certainty' OR 'distance' ... }
>>> { ... 'thermal': "e5dc4a4c-ef0f-3aed-89a3-a73435c6bbcf", ... 'certainty': 0.7 # or 'distance' ... }
With encoded True:
>>> content = { ... 'thermal': "my_thermal_path.png", ... 'certainty': 0.7 # or 'distance' instead ... } >>> query = client.query.get('Thermal', 'description')\ ... .with_near_thermal(content, encode=True) # <- encode MUST be set to True
OR
>>> my_thermal_file = open("my_thermal_path.png", "br") >>> content = { ... 'thermal': my_thermal_file, ... 'certainty': 0.7 # or 'distance' instead ... } >>> query = client.query.get('Thermal', 'description')\ ... .with_near_thermal(content, encode=True) # <- encode MUST be set to True >>> my_thermal_file.close()
With encoded False:
>>> from weaviate.util import file_encoder_b64 >>> encoded_thermal = file_encoder_b64("my_thermal_path.png") >>> content = { ... 'thermal': encoded_thermal, ... 'certainty': 0.7 # or 'distance' instead ... } >>> query = client.query.get('Thermal', 'description')\ ... .with_near_thermal(content, encode=False) # <- encode MUST be set to False
OR
>>> from weaviate.util import file_encoder_b64 >>> with open("my_thermal_path.png", "br") as my_thermal_file: ... encoded_thermal = file_encoder_b64(my_thermal_file) >>> content = { ... 'thermal': encoded_thermal, ... 'certainty': 0.7 # or 'distance' instead ... } >>> query = client.query.get('Thermal', 'description')\ ... .with_near_thermal(content, encode=False) # <- encode MUST be set to False
Encode Thermal yourself:
>>> import base64 >>> with open("my_thermal_path.png", "br") as my_thermal_file: ... encoded_thermal = base64.b64encode(my_thermal_file.read()).decode("utf-8") >>> content = { ... 'thermal': encoded_thermal, ... 'certainty': 0.7 # or 'distance' instead ... } >>> query = client.query.get('Thermal', 'description')\ ... .with_near_thermal(content, encode=False) # <- encode MUST be set to False
Returns
- weaviate.gql.get.GetBuilder
The updated GetBuilder.
Raises
- AttributeError
If another ‘near’ filter was already set.
- with_near_vector(content: dict) GetBuilder [source]
Set nearVector filter.
Parameters
- contentdict
The content of the nearVector filter to set. See examples below.
Examples
Content full prototype:
>>> content = { ... 'vector' : <list of float>, ... # certainty ONLY with `cosine` distance specified in the schema ... 'certainty': <float>, # Optional, either 'certainty' OR 'distance' ... 'distance': <float>, # Optional, either 'certainty' OR 'distance' ... }
- NOTE: Supported types for ‘vector’ are list, ‘numpy.ndarray`, torch.Tensor
and tf.Tensor.
Full content:
>>> content = { ... 'vector' : [.1, .2, .3, .5], ... 'certainty': 0.75, # or 'distance' ... }
Minimal content:
>>> content = { ... 'vector' : [.1, .2, .3, .5] ... }
Or
>>> content = { ... 'vector' : torch.tensor([.1, .2, .3, .5]) ... }
Or
>>> content = { ... 'vector' : torch.tensor([[.1, .2, .3, .5]]) # it is going to be squeezed. ... }
Returns
- weaviate.gql.get.GetBuilder
The updated GetBuilder.
Raises
- AttributeError
If another ‘near’ filter was already set.
- with_near_video(content: dict, encode: bool = True) GetBuilder [source]
Set nearVideo filter.
Parameters
- contentdict
The content of the nearVideo filter to set. See examples below.
- encodebool, optional
Whether to encode the content[“video”] to base64 and convert to string. If True, the content[“video”] can be an video path or a file opened in binary read mode. If False, the content[“video”] MUST be a base64 encoded string (NOT bytes, i.e. NOT binary string that looks like this: b’BASE64ENCODED’ but simple ‘BASE64ENCODED’). By default True.
Examples
Content prototype:
>>> content = { ... 'video': <str or binary read file>, ... # certainty ONLY with `cosine` distance specified in the schema ... 'certainty': <float>, # Optional, either 'certainty' OR 'distance' ... 'distance': <float>, # Optional, either 'certainty' OR 'distance' ... }
>>> { ... 'video': "e5dc4a4c-ef0f-3aed-89a3-a73435c6bbcf", ... 'certainty': 0.7 # or 'distance' ... }
With encoded True:
>>> content = { ... 'video': "my_video_path.avi", ... 'certainty': 0.7 # or 'distance' instead ... } >>> query = client.query.get('Video', 'description')\ ... .with_near_video(content, encode=True) # <- encode MUST be set to True
OR
>>> my_video_file = open("my_video_path.avi", "br") >>> content = { ... 'video': my_video_file, ... 'certainty': 0.7 # or 'distance' instead ... } >>> query = client.query.get('Video', 'description')\ ... .with_near_video(content, encode=True) # <- encode MUST be set to True >>> my_video_file.close()
With encoded False:
>>> from weaviate.util import file_encoder_b64 >>> encoded_video = file_encoder_b64("my_video_path.avi") >>> content = { ... 'video': encoded_video, ... 'certainty': 0.7 # or 'distance' instead ... } >>> query = client.query.get('Video', 'description')\ ... .with_near_video(content, encode=False) # <- encode MUST be set to False
OR
>>> from weaviate.util import file_encoder_b64, video_decoder_b64 >>> with open("my_video_path.avi", "br") as my_video_file: ... encoded_video = file_encoder_b64(my_video_file) >>> content = { ... 'video': encoded_video, ... 'certainty': 0.7 # or 'distance' instead ... } >>> query = client.query.get('Video', 'description')\ ... .with_near_video(content, encode=False) # <- encode MUST be set to False
Encode Video yourself:
>>> import base64 >>> with open("my_video_path.avi", "br") as my_video_file: ... encoded_video = base64.b64encode(my_video_file.read()).decode("utf-8") >>> content = { ... 'video': encoded_video, ... 'certainty': 0.7 # or 'distance' instead ... } >>> query = client.query.get('Video', 'description')\ ... .with_near_video(content, encode=False) # <- encode MUST be set to False
Returns
- weaviate.gql.get.GetBuilder
The updated GetBuilder.
Raises
- AttributeError
If another ‘near’ filter was already set.
- with_offset(offset: int) GetBuilder [source]
The offset of objects returned, i.e. the starting index of the returned objects should be used in conjunction with the with_limit method.
Parameters
- offsetint
The offset used for the returned objects.
Returns
- weaviate.gql.get.GetBuilder
The updated GetBuilder.
Raises
- ValueError
If ‘offset’ is non-positive.
- with_sort(content: list | dict) GetBuilder [source]
Sort objects based on specific field/s. Multiple sort fields can be used, the objects are going to be sorted according to order of the sort configs passed. This method can be called multiple times and it does not overwrite the last entry but appends it to the previous ones, see examples below.
Parameters
- contentUnion[list, dict]
The content of the Sort filter. Can be a single Sort configuration or a list of configurations.
Examples
The content should have this form:
>>> content = { ... 'path': ['name'] # Path to the property that should be used ... 'order': 'asc' # Sort order, possible values: asc, desc ... } >>> client.query.get('Author', ['name', 'address'])\ ... .with_sort(content)
Or a list of sort configurations:
>>> content = [ ... { ... 'path': ['name'] # Path to the property that should be used ... 'order': 'asc' # Sort order, possible values: asc, desc ... }, ... 'path': ['address'] # Path to the property that should be used ... 'order': 'desc' # Sort order, possible values: asc, desc ... } ... ]
If we have a list we can add it in 2 ways. Pass the list:
>>> client.query.get('Author', ['name', 'address'])\ ... .with_sort(content)
Or one configuration at a time:
>>> client.query.get('Author', ['name', 'address'])\ ... .with_sort(content[0]) ... .with_sort(content[1])
It is possible to call this method multiple times with lists only too.
Returns
- weaviate.gql.get.GetBuilder
The updated GetBuilder.
- with_tenant(tenant: str) GetBuilder [source]
Sets a tenant for the query.
- with_where(content: dict) GetBuilder [source]
Set where filter.
Parameters
- contentdict
The content of the where filter to set. See examples below.
Examples
The content prototype is like this:
>>> content = { ... 'operator': '<operator>', ... 'operands': [ ... { ... 'path': [path], ... 'operator': '<operator>' ... '<valueType>': <value> ... }, ... { ... 'path': [<matchPath>], ... 'operator': '<operator>', ... '<valueType>': <value> ... } ... ] ... }
This is a complete where filter but it does not have to be like this all the time.
Single operand:
>>> content = { ... 'path': ["wordCount"], # Path to the property that should be used ... 'operator': 'GreaterThan', # operator ... 'valueInt': 1000 # value (which is always = to the type of the path property) ... }
Or
>>> content = { ... 'path': ["id"], ... 'operator': 'Equal', ... 'valueString': "e5dc4a4c-ef0f-3aed-89a3-a73435c6bbcf" ... }
Multiple operands:
>>> content = { ... 'operator': 'And', ... 'operands': [ ... { ... 'path': ["wordCount"], ... 'operator': 'GreaterThan', ... 'valueInt': 1000 ... }, ... { ... 'path': ["wordCount"], ... 'operator': 'LessThan', ... 'valueInt': 1500 ... } ... ] ... }
Returns
- weaviate.gql.get.GetBuilder
The updated GetBuilder.
- class weaviate.gql.get.GroupBy(path: List[str], groups: int, objects_per_group: int)[source]
Bases:
object
- groups: int
- objects_per_group: int
- path: List[str]
- class weaviate.gql.get.Hybrid(query: str, alpha: float | None, vector: List[float] | None, properties: List[str] | None, fusion_type: weaviate.gql.get.HybridFusion | None)[source]
Bases:
object
- alpha: float | None
- fusion_type: HybridFusion | None
- properties: List[str] | None
- query: str
- vector: List[float] | None
weaviate.gql.multi_get module
GraphQL Get command.
- class weaviate.gql.multi_get.MultiGetBuilder(get_builder: List[GetBuilder], connection: Connection)[source]
Bases:
GraphQL
GetBuilder class used to create GraphQL queries.
Initialize a MultiGetBuilder class instance.
Parameters
- get_builderlist of GetBuilder
GetBuilder objects for a single request each.
- connectionweaviate.connect.Connection
Connection object to an active and running Weaviate instance.
Examples
To create a ‘multi_get’ object using several ‘get’ request at the same time use:
>>> client.query.multi_get( ... [ ... client.query.get("Ship", ["name"]).with_alias("one"), ... client.query.get("Ship", ["size"]).with_alias("two"), ... client.query.get("Person", ["name"]) ... ] with_alias() needs to be used if the same 'class_name' is used twice during the same 'multi_get' request.
Raises
- TypeError
If ‘get_builder’ is of wrong type.
weaviate.gql.query module
GraphQL query module.
- class weaviate.gql.query.Query(connection: Connection)[source]
Bases:
object
Query class used to make get and/or aggregate GraphQL queries.
Initialize a Classification class instance.
Parameters
- connectionweaviate.connect.Connection
Connection object to an active and running Weaviate instance.
- aggregate(class_name: str) AggregateBuilder [source]
Instantiate an AggregateBuilder for GraphQL aggregate requests.
Parameters
- class_namestr
Class name of the objects to be aggregated.
Returns
- AggregateBuilder
An AggregateBuilder to make GraphQL aggregate requests from weaviate.
- get(class_name: str, properties: Sequence[str | LinkTo] | str | None = None) GetBuilder [source]
Instantiate a GetBuilder for GraphQL get requests.
Parameters
- class_namestr
Class name of the objects to interact with.
- propertieslist of str and ReferenceProperty, str or None
Properties of the objects to get, by default None
Returns
- GetBuilder
A GetBuilder to make GraphQL get requests from weaviate.
- multi_get(get_builder: List[GetBuilder]) MultiGetBuilder [source]
Instantiate a MultiGetBuilder for GraphQL multi_get requests. Bundles multiple get requests into one.
Parameters
- get_builderlist of GetBuilder
List of GetBuilder objects for a single request each.
Returns
- MultiGetBuilder
A MultiGetBuilder to make GraphQL get multiple requests from weaviate.
- raw(gql_query: str) Dict[str, Any] [source]
Allows to send simple graph QL string queries. Be cautious of injection risks when generating query strings.
Parameters
- gql_querystr
GraphQL query as a string.
Returns
- dict
Data response of the query.
Examples
>>> query = """ ... { ... Get { ... Article(limit: 2) { ... title ... hasAuthors { ... ... on Author { ... name ... } ... } ... } ... } ... } ... """ >>> client.query.raw(query) { "data": { "Get": { "Article": [ { "hasAuthors": [ { "name": "Jonathan Wilson" } ], "title": "Sergio Agüero has been far more than a great goalscorer for Manchester City" }, { "hasAuthors": [ { "name": "Emma Elwick-Bates" } ], "title": "At Swarovski, Giovanna Engelbert Is Crafting Jewels As Exuberantly Joyful As She Is" } ] } }, "errors": null }
Raises
- TypeError
If ‘gql_query’ is not of type str.
- requests.ConnectionError
If the network connection to weaviate fails.
- weaviate.UnexpectedStatusCodeException
If weaviate reports a none OK status.