weaviate.gql

GraphQL module used to create get and/or aggregate GraphQL requests from Weaviate.

weaviate.gql.aggregate

GraphQL Aggregate command.

class weaviate.gql.aggregate.Hybrid(content: dict)[source]

Bases: object

Parameters:: content (dict)

query: str | None

alpha: float | None

vector: List[float] | None

properties: List[str] | None

target_vectors: List[str] | None

max_vector_distance: List[str] | None

class weaviate.gql.aggregate.AggregateBuilder(class_name)[source]

Bases: GraphQL

AggregateBuilder class used to aggregate Weaviate objects.

Initialize a AggregateBuilder class instance.

Parameters:: class_name (str) – Class name of the objects to be aggregated.

with_tenant(tenant)[source]

Sets a tenant for the query.

Parameters:: tenant (str)
Return type:: AggregateBuilder

with_meta_count()[source]

Set Meta Count to True.

Returns:: Updated AggregateBuilder.
Return type:: AggregateBuilder

with_object_limit(limit)[source]

Set objectLimit to limit vector search results used within the aggregation query only when with near<MEDIA> filter.

Parameters:: limit (int) – The object limit.
Returns:: Updated AggregateBuilder.
Return type:: AggregateBuilder

with_limit(limit)[source]

Set limit to limit the number of returned results from the aggregation query.

Parameters:: limit (int) – The limit.
Returns:: Updated AggregateBuilder.
Return type:: AggregateBuilder

with_fields(field)[source]

Include a field in the aggregate query.

Parameters:: field (str) – Field to include in the aggregate query. e.g. ‘<property_name> { count }’
Returns:: Updated AggregateBuilder.
Return type:: AggregateBuilder

with_where(content)[source]

Set ‘where’ filter.

Parameters:: content (dict) – The where filter to include in the aggregate query. See examples below.
Returns:: Updated AggregateBuilder.
Return type:: AggregateBuilder

with_hybrid(content)[source]

Get objects using bm25 and vector, then combine the results using a reciprocal ranking algorithm.

Parameters:: content (dict) – The content of the hybrid filter to set.
Returns:: Updated AggregateBuilder.
Return type:: AggregateBuilder

with_group_by_filter(properties)[source]

Add a group by filter to the query. Might requires the user to set an additional group by clause using with_fields(..).

Parameters:: properties (List[str]) – The list of properties that are included in the group by filter. Generates a filter like: ‘groupBy: [“property1”, “property2”]’ from a list [“property1”, “property2”]
Returns:: Updated AggregateBuilder.
Return type:: AggregateBuilder

with_near_text(content)[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:: content (dict) – The content of the nearText filter to set. See examples below.
Returns:: Updated AggregateBuilder.
Raises:: AttributeError – If another ‘near’ filter was already set.
Return type:: AggregateBuilder

with_near_vector(content)[source]

Set nearVector filter.

Parameters:: content (dict) – The content of the nearVector filter to set. See examples below.
Returns:: Updated AggregateBuilder.
Raises:: AttributeError – If another ‘near’ filter was already set.
Return type:: AggregateBuilder

with_near_object(content)[source]

Set nearObject filter.

Parameters:: content (dict) – The content of the nearObject filter to set. See examples below.
Returns:: Updated AggregateBuilder.
Raises:: AttributeError – If another ‘near’ filter was already set.
Return type:: AggregateBuilder

with_near_image(content, encode=True)[source]

Set nearImage filter.

Parameters:

content (dict) – The content of the nearImage filter to set. See examples below.
encode (bool) – 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.

Returns:

Updated AggregateBuilder.

Raises:

AttributeError – If another ‘near’ filter was already set.

Return type:

AggregateBuilder

_abc_impl = <_abc._abc_data object>

with_near_audio(content, encode=True)[source]

Set nearAudio filter.

Parameters:

content (dict) – The content of the nearAudio filter to set. See examples below.
encode (bool) – 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.

Returns:

Updated AggregateBuilder.

Raises:

AttributeError – If another ‘near’ filter was already set.

Return type:

AggregateBuilder

with_near_video(content, encode=True)[source]

Set nearVideo filter.

Parameters:

content (dict) – The content of the nearVideo filter to set. See examples below.
encode (bool) – 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.

Returns:

Updated AggregateBuilder.

Raises:

AttributeError – If another ‘near’ filter was already set.

Return type:

AggregateBuilder

with_near_depth(content, encode=True)[source]

Set nearDepth filter.

Parameters:

content (dict) – The content of the nearDepth filter to set. See examples below.
encode (bool) – 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.

Returns:

Updated AggregateBuilder.

Raises:

AttributeError – If another ‘near’ filter was already set.

Return type:

AggregateBuilder

with_near_thermal(content, encode=True)[source]

Set nearThermal filter.

Parameters:

content (dict) – The content of the nearThermal filter to set. See examples below.
encode (bool) – 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.

Returns:

Updated AggregateBuilder.

Raises:

AttributeError – If another ‘near’ filter was already set.

Return type:

AggregateBuilder

with_near_imu(content, encode=True)[source]

Set nearIMU filter.

Parameters:

content (dict) – The content of the nearIMU filter to set. See examples below.
encode (bool) – 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.

Returns:

Updated AggregateBuilder.

Raises:

AttributeError – If another ‘near’ filter was already set.

Return type:

AggregateBuilder

build()[source]

Build the query and return the string.

Returns:: The GraphQL query as a string.
Return type:: str

weaviate.gql.filter

GraphQL filters for Get and Aggregate commands. GraphQL abstract class for GraphQL commands to inherit from.

class weaviate.gql.filter.MediaType(*values)[source]

Bases: Enum

IMAGE = 'image'

AUDIO = 'audio'

VIDEO = 'video'

THERMAL = 'thermal'

DEPTH = 'depth'

IMU = 'imu'

class weaviate.gql.filter.GraphQL[source]

Bases: ABC

A base abstract class for GraphQL commands, such as Get, Aggregate.

abstractmethod build()[source]

Build method to be overloaded by the child classes. It should return the GraphQL query as a str.

Returns:: The query.
Return type:: str

_abc_impl = <_abc._abc_data object>

class weaviate.gql.filter.Filter(content)[source]

Bases: ABC

A base abstract class for all filters.

Initialize a Filter class instance.

Parameters:: content (dict) – The content of the Filter clause.

property content: dict

_abc_impl = <_abc._abc_data object>

class weaviate.gql.filter.NearText(content)[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:

content (dict) – 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.

_abc_impl = <_abc._abc_data object>

class weaviate.gql.filter.NearVector(content)[source]

Bases: Filter

NearVector class used to filter weaviate objects.

Initialize a NearVector class instance.

Parameters:

content (dict) – 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.

_abc_impl = <_abc._abc_data object>

class weaviate.gql.filter.NearObject(content, is_server_version_14)[source]

Bases: Filter

NearObject class used to filter weaviate objects.

Initialize a NearVector class instance.

Parameters:

content (dict) – The content of the nearVector clause.
is_server_version_14 (bool) – 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!

_abc_impl = <_abc._abc_data object>

class weaviate.gql.filter.Ask(content)[source]

Bases: Filter

Ask class used to filter weaviate objects by asking a question.

Initialize a Ask class instance.

Parameters:

content (dict) – 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.

_abc_impl = <_abc._abc_data object>

class weaviate.gql.filter.NearMedia(content, media_type)[source]

Bases: Filter

Initialize a NearMedia class instance.

Parameters:

content (dict) – The content of the near<Media> clause.
media_type (MediaType)

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.

_abc_impl = <_abc._abc_data object>

class weaviate.gql.filter.NearImage(content)[source]

Bases: NearMedia

NearImage class used to filter weaviate objects.

Initialize a NearImage class instance.

Parameters:

content (dict) – 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.

_abc_impl = <_abc._abc_data object>

class weaviate.gql.filter.NearVideo(content)[source]

Bases: NearMedia

NearVideo class used to filter weaviate objects.

Initialize a NearVideo class instance.

Parameters:

content (dict) – 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.

_abc_impl = <_abc._abc_data object>

class weaviate.gql.filter.NearAudio(content)[source]

Bases: NearMedia

NearAudio class used to filter weaviate objects.

Initialize a NearAudio class instance.

Parameters:

content (dict) – 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.

_abc_impl = <_abc._abc_data object>

class weaviate.gql.filter.NearDepth(content)[source]

Bases: NearMedia

NearDepth class used to filter weaviate objects.

Initialize a NearDepth class instance.

Parameters:

content (dict) – 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.

_abc_impl = <_abc._abc_data object>

class weaviate.gql.filter.NearThermal(content)[source]

Bases: NearMedia

NearThermal class used to filter weaviate objects.

Initialize a NearThermal class instance.

Parameters:

content (dict) – 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.

_abc_impl = <_abc._abc_data object>

class weaviate.gql.filter.NearIMU(content)[source]

Bases: NearMedia

NearIMU class used to filter weaviate objects.

Initialize a NearIMU class instance.

Parameters:

content (dict) – 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.

_abc_impl = <_abc._abc_data object>

class weaviate.gql.filter.Sort(content)[source]

Bases: Filter

Sort filter class used to sort weaviate objects.

Initialize a Where filter class instance.

Parameters:

content (dict | list) – 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)[source]

Add more sort clauses to the already existing sort clauses.

Parameters:

content (dict | list) – 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.

Return type:

None

_abc_impl = <_abc._abc_data object>

class weaviate.gql.filter.Where(content)[source]

Bases: Filter

Where filter class used to filter weaviate objects.

Initialize a Where filter class instance.

Parameters:

content (dict) – 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.

_parse_filter(content)[source]

Set filter fields for the Where filter.

Parameters:: content (dict) – The content of the where filter clause.
Raises:: ValueError – If ‘content’ is missing required fields.
Return type:: None

_parse_operator(content)[source]

Set operator fields for the Where filter.

Parameters:: content (dict) – The content of the where filter clause.
Raises:: ValueError – If ‘content’ is missing required fields.
Return type:: None

_abc_impl = <_abc._abc_data object>

weaviate.gql.filter._convert_value_type(_type)[source]

Convert the value type to match json formatting required by the Weaviate-defined GraphQL endpoints.

NOTE: This is crucially different to the Batch REST endpoints wherein the where filter is also used.

Parameters:: _type (str) – The Python-defined type to be converted.
Returns:: The string interpretation of the type in Weaviate-defined json format.
Return type:: str

weaviate.gql.filter._render_list(input_list)[source]

Convert a list of values to string (lowercased) to match json formatting.

Parameters:: input_list (list) – The value to be converted
Returns:: The string interpretation of the value in json format.
Return type:: str

weaviate.gql.filter._render_list_date(input_list)[source]

Parameters:: input_list (list)
Return type:: str

weaviate.gql.filter._check_is_list(value, _type)[source]

Checks whether the provided value is a list to match the given value_type.

Parameters:

value (Any) – The value to be checked.
_type (str) – The type to be checked against.

Raises:

TypeError – If the value is not a list.

Return type:

None

weaviate.gql.filter._check_is_not_list(value, _type)[source]

Checks whether the provided value is a list to match the given value_type.

Parameters:

value (Any) – The value to be checked.
_type (str) – The type to be checked against.

Raises:

TypeError – If the value is a list.

Return type:

None

weaviate.gql.filter._geo_range_to_str(value)[source]

Convert the valueGeoRange object to match json formatting.

Parameters:: value (dict) – The value to be converted.
Returns:: The string interpretation of the value in json format.
Return type:: str

weaviate.gql.filter._bool_to_str(value)[source]

Convert a bool value to string (lowercased) to match json formatting.

Parameters:: value (bool) – The value to be converted
Returns:: The string interpretation of the value in json format.
Return type:: str

weaviate.gql.filter._check_direction_clause(direction)[source]

Validate the direction sub clause.

Parameters:

direction (dict) – A sub clause of the Explore filter.

Raises:

TypeError – If ‘direction’ is not a dict.
TypeError – If the value of the “force” key is not float.
ValueError – If no “force” key in the ‘direction’.

Return type:

None

weaviate.gql.filter._check_concept(content)[source]

Validate the concept sub clause.

Parameters:

content (dict) – An Explore (sub) clause to check for ‘concepts’.

Raises:

ValueError – If no “concepts” key in the ‘content’ dict.
TypeError – If the value of the “concepts” is of wrong type.

Return type:

None

weaviate.gql.filter._check_objects(content)[source]

Validate the objects sub clause of the move clause.

Parameters:

content (dict) – An Explore (sub) clause to check for ‘objects’.

Raises:

ValueError – If no “concepts” key in the ‘content’ dict.
TypeError – If the value of the “concepts” is of wrong type.

Return type:

None

weaviate.gql.filter._check_type(var_name, value, dtype)[source]

Check key-value type.

Parameters:

var_name (str) – The variable name for which to check the type (used for error message)!
value (Any) – The value for which to check the type.
dtype (Tuple[type, type] | type) – The expected data type of the value.

Raises:

TypeError – If the value type does not match the expected dtype.

Return type:

None

weaviate.gql.filter._find_value_type(content)[source]

Find the correct type of the content.

Parameters:: content (dict) – The content for which to find the appropriate data type.
Returns:: The correct data type.
Raises:: ValueError – If missing required fields.
Return type:: str

weaviate.gql.filter._move_clause_objects_to_str(objects)[source]

Creates the Weaviate moveTo/moveAwayFrom clause given the list of objects.

Parameters:: objects (list) – The list of objects to be used for the moveTo/moveAwayFrom clause.
Returns:: The moveTo/moveAwayFrom clause as a string.
Return type:: str