# Weaviate Filter
The `weaviate-filter` package provides a convenient way to build GraphQL filters for [Weaviate](https://weaviate.io/). The main class, `GraphQLFilter`, allows you to create complex filters by adding conditions and operands, and then retrieve the final filter object.
## Installation
To install the `weaviate-filter` package, you can use pip:
```
pip install weaviate-filter
```
## Usage
To use the `weaviate-filter` package, you first need to import the `GraphQLFilter` class and create an instance of it:
```python
from weaviate_filter import GraphQLFilter
filter = GraphQLFilter()
```
### Adding a Condition
You can add a condition to the filter by using the `add_condition` method:
```python
filter.add_condition(path="name", operator="Like", value_type="valueString", value="John")
```
- `path`: The path of the property (e.g., "name").
- `operator`: The operator to use for the condition (e.g., "Like").
- `value_type`: The type of the value (e.g., "valueString").
- `value`: The value for the condition (e.g., "John").
### Adding Operands
You can add operands to the filter by using the `add_operands` method:
```python
filter.add_operands(operator="And", operand1, operand2)
```
- `operator`: The operator to use for the operands (e.g., "And").
- `operands`: The operands to add.
### Adding List Conditions as Operands
You can add a list of conditions as operands to the filter by using the `add_list_conditions_as_operands` method:
```python
filter.add_list_conditions_as_operands(path="name", operator="Like", value_type="valueString", values_list=["John", "Doe"])
```
- `path`: The path of the property (e.g., "name").
- `operator`: The operator to use for the conditions (e.g., "Like").
- `value_type`: The type of the values (e.g., "valueString").
- `values_list`: The list of values for the conditions (e.g., ["John", "Doe"]).
- `condition_operator` (optional): The operator to use for the operands (e.g., "Or"). Defaults to "Or".
### Adding Conditions for Multiple Paths
You can add conditions for multiple paths as operands to the filter by using the `add_conditions_for_multiple_paths` method:
```python
filter.add_conditions_for_multiple_paths(paths=["name", "age"], operator="Equal", value_type="valueString", value="John")
```
- `paths`: The paths of the properties (e.g., ["name", "age"]).
- `operator`: The operator to use for the conditions (e.g., "Equal").
- `value_type`: The type of the value (e.g., "valueString").
- `value`: The value for the conditions (e.g., "John").
- `condition_operator` (optional): The operator to use for the operands (e.g., "Or"). Defaults to "Or".
### Getting the Filter
Once you have added all the conditions and operands, you can get the final filter object by using the `get_filter` method:
```python
final_filter = filter.get_filter(operator="And")
```
- `operator` (optional): The operator for the filter (e.g., "And"). Defaults to "And".
The `get_filter` method will return a dictionary with the final filter object.
## Example
Here is a complete example of using the `weaviate-filter` package:
```python
from weaviate_filter import GraphQLFilter
# Create a filter
filter = GraphQLFilter()
# Add a condition
filter.add_condition(path="name", operator="Like", value_type="valueString", value="John")
# Add operands
operand1 = {"path": "age", "operator": "GreaterThan", "valueInt": 30}
operand2 = {"path": "age", "operator": "LessThan", "valueInt": 50}
filter.add_operands(operator="And", operand1, operand2)
# Add list conditions as operands
filter.add_list_conditions_as_operands(path="name", operator="Like", value_type="valueString", values_list=["John", "Doe"])
# Add conditions for multiple paths
filter.add_conditions_for_multiple_paths(paths=["name", "age"], operator="Equal", value_type="valueString", value="John")
# Get the final filter object
final_filter = filter.get_filter(operator="And")
print(final_filter)
```
Output:
```
{'operator': 'And', 'operands': [{'operator': 'And', 'operands': [{'path': 'age', 'operator': 'GreaterThan', 'valueInt': 30}, {'path': 'age', 'operator': 'LessThan', 'valueInt': 50}]}, {'operator': 'Or', 'operands': [{'path': 'name', 'operator': 'Like', 'valueString': 'John'}, {'path': 'name', 'operator': 'Like', 'valueString': 'Doe'}]}, {'operator': 'Or', 'operands': [{'path': ['name'], 'operator': 'Equal', 'valueString': 'John'}, {'path': ['age'], 'operator': 'Equal', 'valueString': 'John'}]}]}
```
# Real Use Case Demo
1. **Import Required Modules**:
```python
import weaviate
from sentence_transformers import SentenceTransformer
from weaviate_filter import GraphQLFilter
```
Import the required modules. This includes the Weaviate client, the Sentence Transformers library for encoding the query, and the GraphQLFilter class for constructing the query filter.
2. **Initialize SentenceTransformer Model**:
```python
model = SentenceTransformer('sentence-transformers/all-MiniLM-L6-v2')
```
Initialize the SentenceTransformer model. This model is used to convert the text query into a vector.
3. **Setup Weaviate Client**:
```python
WEAVIATE_URL = ""
WEAVIATE_API_KEY = ""
client = weaviate.Client(
url=WEAVIATE_URL, # Replace w/ your endpoint
auth_client_secret=weaviate.AuthApiKey(api_key=WEAVIATE_API_KEY), # Replace w/ your Weaviate instance API key
)
```
Set up the Weaviate client. You need to replace `WEAVIATE_URL` and `WEAVIATE_API_KEY` with your own Weaviate instance's URL and API key.
4. **Define Filters**:
```python
genders = ["M", "F"]
countries = ["Germany"]
labels = ["dlf", "building"]
```
Define the filters you want to apply. In this example, we are filtering for entries with gender "M" or "F", birth_country "Germany", and labels "dlf" or "building" with a value greater than or equal to 1.
5. **Create Filter**:
```python
filter = GraphQLFilter()
filter.add_list_conditions_as_operands(["gender"], "Equal", "valueText", genders, "Or")
filter.add_list_conditions_as_operands(["birth_country"], "Equal", "valueText", countries, "Or")
filter.add_conditions_for_multiple_paths(labels, "GreaterThanEqual", "valueNumber", 1, "Or")
where_filter = filter.get_filter(operator="Or")
```
Create the filter using the `GraphQLFilter` class. The `add_list_conditions_as_operands` method is used to add a list of conditions as operands with a specified operator ("And" or "Or"). The `add_conditions_for_multiple_paths` method is used to add conditions for multiple paths with a specified operator. Finally, the `get_filter` method is used to get the final filter with a specified operator.
6. **Define and Encode Query**:
```python
query = "We were hungry"
query_vector = model.encode(query)
```
Define the query and encode it into a vector using the SentenceTransformer model.
7. **Create nearVector Dictionary**:
```python
nearVector = {
"vector": query_vector
}
```
Create the `nearVector` dictionary with the encoded query vector.
8. **Define Field Options**:
```python
field_options = ["gender", "window_text", "birth_country", "dlf", "building"]
```
Define the fields you want to retrieve in the query.
9. **Perform Query**:
```python
result = client.query.get(
"Window", field_options
).with_near_vector(
nearVector
).with_limit(2).with_additional(['certainty']
).with_where(where_filter).do()
```
Perform the query using the Weaviate client. The `with_near_vector` method is used to add the `nearVector` to the query. The `with_limit` method is used to limit the number of results. The `with_additional` method is used to add additional fields to the query. The `with_where` method is used to add the `where` filter to the query.
10. **Print Results**:
```python
for r in result["data"]["Get"]["Window"]:
print(r)
```
Print the results of the query.
Raw data
{
"_id": null,
"home_page": "https://github.com/wjbmattingly/weaviate-filter",
"name": "weaviate-filter",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "",
"keywords": "",
"author": "WJB Mattingly",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/11/51/318c38c9d97e0e9a064c44c3984daac0fd985505a69986f3f8e42a4989a6/weaviate_filter-0.0.3.tar.gz",
"platform": null,
"description": "# Weaviate Filter\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\nThe `weaviate-filter` package provides a convenient way to build GraphQL filters for [Weaviate](https://weaviate.io/). The main class, `GraphQLFilter`, allows you to create complex filters by adding conditions and operands, and then retrieve the final filter object.\r\n\r\n## Installation\r\n\r\nTo install the `weaviate-filter` package, you can use pip:\r\n\r\n\r\n\r\n```\r\npip install weaviate-filter\r\n```\r\n\r\n## Usage\r\n\r\nTo use the `weaviate-filter` package, you first need to import the `GraphQLFilter` class and create an instance of it:\r\n\r\n```python\r\nfrom weaviate_filter import GraphQLFilter\r\n\r\nfilter = GraphQLFilter()\r\n```\r\n\r\n### Adding a Condition\r\n\r\nYou can add a condition to the filter by using the `add_condition` method:\r\n\r\n```python\r\nfilter.add_condition(path=\"name\", operator=\"Like\", value_type=\"valueString\", value=\"John\")\r\n```\r\n\r\n- `path`: The path of the property (e.g., \"name\").\r\n- `operator`: The operator to use for the condition (e.g., \"Like\").\r\n- `value_type`: The type of the value (e.g., \"valueString\").\r\n- `value`: The value for the condition (e.g., \"John\").\r\n\r\n### Adding Operands\r\n\r\nYou can add operands to the filter by using the `add_operands` method:\r\n\r\n```python\r\nfilter.add_operands(operator=\"And\", operand1, operand2)\r\n```\r\n\r\n- `operator`: The operator to use for the operands (e.g., \"And\").\r\n- `operands`: The operands to add.\r\n\r\n### Adding List Conditions as Operands\r\n\r\nYou can add a list of conditions as operands to the filter by using the `add_list_conditions_as_operands` method:\r\n\r\n```python\r\nfilter.add_list_conditions_as_operands(path=\"name\", operator=\"Like\", value_type=\"valueString\", values_list=[\"John\", \"Doe\"])\r\n```\r\n\r\n- `path`: The path of the property (e.g., \"name\").\r\n- `operator`: The operator to use for the conditions (e.g., \"Like\").\r\n- `value_type`: The type of the values (e.g., \"valueString\").\r\n- `values_list`: The list of values for the conditions (e.g., [\"John\", \"Doe\"]).\r\n- `condition_operator` (optional): The operator to use for the operands (e.g., \"Or\"). Defaults to \"Or\".\r\n\r\n### Adding Conditions for Multiple Paths\r\n\r\nYou can add conditions for multiple paths as operands to the filter by using the `add_conditions_for_multiple_paths` method:\r\n\r\n```python\r\nfilter.add_conditions_for_multiple_paths(paths=[\"name\", \"age\"], operator=\"Equal\", value_type=\"valueString\", value=\"John\")\r\n```\r\n\r\n- `paths`: The paths of the properties (e.g., [\"name\", \"age\"]).\r\n- `operator`: The operator to use for the conditions (e.g., \"Equal\").\r\n- `value_type`: The type of the value (e.g., \"valueString\").\r\n- `value`: The value for the conditions (e.g., \"John\").\r\n- `condition_operator` (optional): The operator to use for the operands (e.g., \"Or\"). Defaults to \"Or\".\r\n\r\n### Getting the Filter\r\n\r\nOnce you have added all the conditions and operands, you can get the final filter object by using the `get_filter` method:\r\n\r\n```python\r\nfinal_filter = filter.get_filter(operator=\"And\")\r\n```\r\n\r\n- `operator` (optional): The operator for the filter (e.g., \"And\"). Defaults to \"And\".\r\n\r\nThe `get_filter` method will return a dictionary with the final filter object.\r\n\r\n## Example\r\n\r\nHere is a complete example of using the `weaviate-filter` package:\r\n\r\n```python\r\nfrom weaviate_filter import GraphQLFilter\r\n\r\n# Create a filter\r\nfilter = GraphQLFilter()\r\n\r\n# Add a condition\r\nfilter.add_condition(path=\"name\", operator=\"Like\", value_type=\"valueString\", value=\"John\")\r\n\r\n# Add operands\r\noperand1 = {\"path\": \"age\", \"operator\": \"GreaterThan\", \"valueInt\": 30}\r\noperand2 = {\"path\": \"age\", \"operator\": \"LessThan\", \"valueInt\": 50}\r\nfilter.add_operands(operator=\"And\", operand1, operand2)\r\n\r\n# Add list conditions as operands\r\nfilter.add_list_conditions_as_operands(path=\"name\", operator=\"Like\", value_type=\"valueString\", values_list=[\"John\", \"Doe\"])\r\n\r\n# Add conditions for multiple paths\r\nfilter.add_conditions_for_multiple_paths(paths=[\"name\", \"age\"], operator=\"Equal\", value_type=\"valueString\", value=\"John\")\r\n\r\n# Get the final filter object\r\nfinal_filter = filter.get_filter(operator=\"And\")\r\n\r\nprint(final_filter)\r\n```\r\n\r\nOutput:\r\n\r\n```\r\n{'operator': 'And', 'operands': [{'operator': 'And', 'operands': [{'path': 'age', 'operator': 'GreaterThan', 'valueInt': 30}, {'path': 'age', 'operator': 'LessThan', 'valueInt': 50}]}, {'operator': 'Or', 'operands': [{'path': 'name', 'operator': 'Like', 'valueString': 'John'}, {'path': 'name', 'operator': 'Like', 'valueString': 'Doe'}]}, {'operator': 'Or', 'operands': [{'path': ['name'], 'operator': 'Equal', 'valueString': 'John'}, {'path': ['age'], 'operator': 'Equal', 'valueString': 'John'}]}]}\r\n```\r\n\r\n# Real Use Case Demo\r\n\r\n\r\n1. **Import Required Modules**:\r\n ```python\r\n import weaviate\r\n from sentence_transformers import SentenceTransformer\r\n from weaviate_filter import GraphQLFilter\r\n ```\r\n Import the required modules. This includes the Weaviate client, the Sentence Transformers library for encoding the query, and the GraphQLFilter class for constructing the query filter.\r\n\r\n2. **Initialize SentenceTransformer Model**:\r\n ```python\r\n model = SentenceTransformer('sentence-transformers/all-MiniLM-L6-v2')\r\n ```\r\n Initialize the SentenceTransformer model. This model is used to convert the text query into a vector.\r\n\r\n3. **Setup Weaviate Client**:\r\n ```python\r\n WEAVIATE_URL = \"\"\r\n WEAVIATE_API_KEY = \"\"\r\n client = weaviate.Client(\r\n url=WEAVIATE_URL, # Replace w/ your endpoint\r\n auth_client_secret=weaviate.AuthApiKey(api_key=WEAVIATE_API_KEY), # Replace w/ your Weaviate instance API key\r\n )\r\n ```\r\n Set up the Weaviate client. You need to replace `WEAVIATE_URL` and `WEAVIATE_API_KEY` with your own Weaviate instance's URL and API key.\r\n\r\n4. **Define Filters**:\r\n ```python\r\n genders = [\"M\", \"F\"]\r\n countries = [\"Germany\"]\r\n labels = [\"dlf\", \"building\"]\r\n ```\r\n Define the filters you want to apply. In this example, we are filtering for entries with gender \"M\" or \"F\", birth_country \"Germany\", and labels \"dlf\" or \"building\" with a value greater than or equal to 1.\r\n\r\n5. **Create Filter**:\r\n ```python\r\n filter = GraphQLFilter()\r\n filter.add_list_conditions_as_operands([\"gender\"], \"Equal\", \"valueText\", genders, \"Or\")\r\n filter.add_list_conditions_as_operands([\"birth_country\"], \"Equal\", \"valueText\", countries, \"Or\")\r\n filter.add_conditions_for_multiple_paths(labels, \"GreaterThanEqual\", \"valueNumber\", 1, \"Or\")\r\n where_filter = filter.get_filter(operator=\"Or\")\r\n ```\r\n Create the filter using the `GraphQLFilter` class. The `add_list_conditions_as_operands` method is used to add a list of conditions as operands with a specified operator (\"And\" or \"Or\"). The `add_conditions_for_multiple_paths` method is used to add conditions for multiple paths with a specified operator. Finally, the `get_filter` method is used to get the final filter with a specified operator.\r\n\r\n6. **Define and Encode Query**:\r\n ```python\r\n query = \"We were hungry\"\r\n query_vector = model.encode(query)\r\n ```\r\n Define the query and encode it into a vector using the SentenceTransformer model.\r\n\r\n7. **Create nearVector Dictionary**:\r\n ```python\r\n nearVector = {\r\n \"vector\": query_vector\r\n }\r\n ```\r\n Create the `nearVector` dictionary with the encoded query vector.\r\n\r\n8. **Define Field Options**:\r\n ```python\r\n field_options = [\"gender\", \"window_text\", \"birth_country\", \"dlf\", \"building\"]\r\n ```\r\n Define the fields you want to retrieve in the query.\r\n\r\n9. **Perform Query**:\r\n ```python\r\n result = client.query.get(\r\n \"Window\", field_options\r\n ).with_near_vector(\r\n nearVector\r\n ).with_limit(2).with_additional(['certainty']\r\n ).with_where(where_filter).do()\r\n ```\r\n Perform the query using the Weaviate client. The `with_near_vector` method is used to add the `nearVector` to the query. The `with_limit` method is used to limit the number of results. The `with_additional` method is used to add additional fields to the query. The `with_where` method is used to add the `where` filter to the query.\r\n\r\n10. **Print Results**:\r\n ```python\r\n for r in result[\"data\"][\"Get\"][\"Window\"]:\r\n print(r)\r\n ```\r\n Print the results of the query.\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A package for creating GraphQL filters for Weaviate",
"version": "0.0.3",
"project_urls": {
"Homepage": "https://github.com/wjbmattingly/weaviate-filter"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "1151318c38c9d97e0e9a064c44c3984daac0fd985505a69986f3f8e42a4989a6",
"md5": "357ef3f5cac49960f974fd0e9f2a3d1c",
"sha256": "ee2961938ba04bf26a6fb84bf9c4c7a79e7e338323de1622e6f8e1a28bc67aa9"
},
"downloads": -1,
"filename": "weaviate_filter-0.0.3.tar.gz",
"has_sig": false,
"md5_digest": "357ef3f5cac49960f974fd0e9f2a3d1c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 4632,
"upload_time": "2023-08-31T09:14:10",
"upload_time_iso_8601": "2023-08-31T09:14:10.025108Z",
"url": "https://files.pythonhosted.org/packages/11/51/318c38c9d97e0e9a064c44c3984daac0fd985505a69986f3f8e42a4989a6/weaviate_filter-0.0.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-08-31 09:14:10",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "wjbmattingly",
"github_project": "weaviate-filter",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "weaviate-filter"
}
JSON
