weaviate.gql

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

class weaviate.gql.Query(connection: weaviate.connect.connection.Connection)

Bases: object

Query class used to make get and/or aggregate GraphQL queries.

Initialize a Classification class instance.

Parameters

connection (weaviate.connect.Connection) – Connection object to an active and running Weaviate instance.

aggregate(class_name: str) → weaviate.gql.aggregate.AggregateBuilder

Instantiate an AggregateBuilder for GraphQL aggregate requests.

Parameters

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

Returns

An AggregateBuilder to make GraphQL aggregate requests from weaviate.

Return type

AggregateBuilder

get(class_name: str, properties: Union[List[str], str]) → weaviate.gql.get.GetBuilder

Instantiate a GetBuilder for GraphQL get requests.

Parameters

  • class_name (str) – Class name of the objects to interact with.

  • properties (list of str or str) – Properties of the objects to get.

Returns

A GetBuilder to make GraphQL get requests from weaviate.

Return type

GetBuilder

raw(gql_query: str) → dict

Allows to send simple graph QL string queries. Be cautious of injection risks when generating query strings.

Parameters

gql_query (str) – GraphQL query as a string.

Returns

Data response of the query.

Return type

dict

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.

weaviate.gql.aggregate

GraphQL Aggregate command.

class weaviate.gql.aggregate.AggregateBuilder(class_name: str, connection: weaviate.connect.connection.Connection)

Bases: weaviate.gql.filter.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.

  • connection (weaviate.connect.Connection) – Connection object to an active and running Weaviate instance.

build() → str

Build the query and return the string.

Returns

The GraphQL query as a string.

Return type

str

with_fields(field: str) → weaviate.gql.aggregate.AggregateBuilder

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

weaviate.gql.aggregate.AggregateBuilder

with_group_by_filter(properties: List[str]) → weaviate.gql.aggregate.AggregateBuilder

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 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

Updated AggregateBuilder.

Return type

weaviate.gql.aggregate.AggregateBuilder

with_meta_count() → weaviate.gql.aggregate.AggregateBuilder

Set Meta Count to True.

Returns

Updated AggregateBuilder.

Return type

weaviate.gql.aggregate.AggregateBuilder

with_near_object(content: dict) → weaviate.gql.aggregate.AggregateBuilder

Set nearObject filter.

Parameters

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

Updated AggregateBuilder.

Return type

weaviate.gql.aggregate.AggregateBuilder

Raises

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

with_near_text(content: dict) → weaviate.gql.aggregate.AggregateBuilder

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.

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

Updated AggregateBuilder.

Return type

weaviate.gql.aggregate.AggregateBuilder

Raises

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

with_near_vector(content: dict) → weaviate.gql.aggregate.AggregateBuilder

Set nearVector filter.

Parameters

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

Updated AggregateBuilder.

Return type

weaviate.gql.aggregate.AggregateBuilder

Raises

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

with_object_limit(limit: int) → weaviate.gql.aggregate.AggregateBuilder

Set objectLimit to limit vector search results only when with near<MEDIA> filter.

Parameters

limit (int) – The object limit.

Returns

Updated AggregateBuilder.

Return type

weaviate.gql.aggregate.AggregateBuilder

with_where(content: dict) → weaviate.gql.aggregate.AggregateBuilder

Set ‘where’ filter.

Parameters

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

Updated AggregateBuilder.

Return type

weaviate.gql.aggregate.AggregateBuilder

weaviate.gql.filter

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

class weaviate.gql.filter.Ask(content: dict)

Bases: weaviate.gql.filter.Filter

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

Initialize a Ask class instance.

Parameters

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

Bases: abc.ABC

A base abstract class for all filters.

Initialize a Filter class instance.

Parameters

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

class weaviate.gql.filter.GraphQL(connection: weaviate.connect.connection.Connection)

Bases: abc.ABC

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

Initialize a GraphQL abstract class instance.

Parameters

connection (weaviate.connect.Connection) – Connection object to an active and running weaviate instance.

abstract build() → str

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

Returns

The query.

Return type

str

do() → dict

Builds and runs the query.

Returns

The response of the query.

Return type

dict

Raises
class weaviate.gql.filter.NearImage(content: dict)

Bases: weaviate.gql.filter.Filter

NearObject class used to filter weaviate objects.

Initialize a NearImage class instance.

Parameters

content (list) – 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.NearObject(content: dict, is_server_version_14: bool)

Bases: weaviate.gql.filter.Filter

NearObject class used to filter weaviate objects.

Initialize a NearVector class instance.

Parameters

  • content (list) – 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!

class weaviate.gql.filter.NearText(content: dict)

Bases: weaviate.gql.filter.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.

class weaviate.gql.filter.NearVector(content: dict)

Bases: weaviate.gql.filter.Filter

NearVector class used to filter weaviate objects.

Initialize a NearVector class instance.

Parameters

content (list) – 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.Sort(content: Union[dict, list])

Bases: weaviate.gql.filter.Filter

Sort filter class used to sort weaviate objects.

Initialize a Where filter class instance.

Parameters

content (list 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: Union[dict, list]) → None

Add more sort clauses to the already existing sort clauses.

Parameters

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

Bases: weaviate.gql.filter.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.

weaviate.gql.get

GraphQL Get command.

class weaviate.gql.get.GetBuilder(class_name: str, properties: Optional[Union[List[str], str]], connection: weaviate.connect.connection.Connection)

Bases: weaviate.gql.filter.GraphQL

GetBuilder class used to create GraphQL queries.

Initialize a GetBuilder class instance.

Parameters

  • class_name (str) – Class name of the objects to interact with.

  • properties (str or list of str) – Properties of the objects to interact with.

  • connection (weaviate.connect.Connection) – Connection object to an active and running Weaviate instance.

Raises

TypeError – If argument/s is/are of wrong type.

build() → str

Build query filter as a string.

Returns

The GraphQL query as a string.

Return type

str

with_additional(properties: Union[List, str, Dict[str, Union[str, List[str]]], Tuple[dict, dict]]) → weaviate.gql.get.GetBuilder

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

properties (str, 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

The updated GetBuilder.

Return type

weaviate.gql.get.GetBuilder

Raises

TypeError – If one of the property is not of a correct data type.

with_ask(content: dict) → weaviate.gql.get.GetBuilder

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

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

The updated GetBuilder.

Return type

weaviate.gql.get.GetBuilder

with_limit(limit: int) → weaviate.gql.get.GetBuilder

The limit of objects returned.

Parameters

limit (int) – The max number of objects returned.

Returns

The updated GetBuilder.

Return type

weaviate.gql.get.GetBuilder

Raises

ValueError – If ‘limit’ is non-positive.

with_near_image(content: dict, encode: bool = True) → weaviate.gql.get.GetBuilder

Set nearImage filter.

Parameters

  • content (dict) – The content of the nearObject filter to set. See examples below.

  • encode (bool, 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

The updated GetBuilder.

Return type

weaviate.gql.get.GetBuilder

Raises

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

with_near_object(content: dict) → weaviate.gql.get.GetBuilder

Set nearObject filter.

Parameters

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

The updated GetBuilder.

Return type

weaviate.gql.get.GetBuilder

Raises

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

with_near_text(content: dict) → weaviate.gql.get.GetBuilder

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.

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

The updated GetBuilder.

Return type

weaviate.gql.get.GetBuilder

Raises

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

with_near_vector(content: dict) → weaviate.gql.get.GetBuilder

Set nearVector filter.

Parameters

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

The updated GetBuilder.

Return type

weaviate.gql.get.GetBuilder

Raises

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

with_offset(offset: int) → weaviate.gql.get.GetBuilder

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

offset (int) – The offset used for the returned objects.

Returns

The updated GetBuilder.

Return type

weaviate.gql.get.GetBuilder

Raises

ValueError – If ‘offset’ is non-positive.

with_sort(content: Union[list, dict]) → weaviate.gql.get.GetBuilder

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

content (Union[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

The updated GetBuilder.

Return type

weaviate.gql.get.GetBuilder

with_where(content: dict) → weaviate.gql.get.GetBuilder

Set where filter.

Parameters

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

The updated GetBuilder.

Return type

weaviate.gql.get.GetBuilder