Neat 265 update docs for raw filter provide simple example (#464)

* update docs, add example, add test

* bump version, add changelog

Makefile

@@ -1,6 +1,6 @@
 .PHONY: run-explorer run-tests run-linters build-ui build-python build-docker run-docker compose-up
 
-version="0.77.5"
+version="0.77.6"
 run-explorer:
 	@echo "Running explorer API server..."
 	# open "http://localhost:8000/static/index.html" || true

cognite/neat/_version.py

@@ -1 +1 @@
-__version__ = "0.77.5"
+__version__ = "0.77.6"

docs/CHANGELOG.md

@@ -15,6 +15,12 @@ Changes are grouped as follows:
 - `Fixed` for any bug fixes.
 - `Security` in case of vulnerabilities.
 
+## [0.77.6] - 23-05-24
+### Improves
+- Documentation on how to use raw filter
+- Added a simple example of Rules with raw filter
+- Added new test for raw filter
+
 ## [0.77.5] - 23-05-24
 ### Fixed
 - `DMSExporter` creates the schema depending on `extension` in metadata field as defined in the

docs/terminology/dmsrules.md

@@ -97,7 +97,7 @@ the most of the views will use a `hasData` filter, for example, the wind turbine
 use a `nodeType` filter `nodeType(power:Polygon)`.
 
 
-#### Setting a manual filter
+#### Setting `hasData` and `nodeType` filters manually
 
 !!! warning annotate "Only for advanced users"
     Setting a manual filter is only recommended for advanced users. If you are not sure what you are doing, we recommend
@@ -111,3 +111,28 @@ You can set manuel filters by specifying the `filter` column in the view sheet.
 * `nodeType` - This will set a `nodeType` filter with the same node id as the view.
 * `nodeType(my_space:my_node)` - This will set a `nodeType` filter with the specified node id.
 * `nodeType(my_space:my_node, my_space:my_node2)` - This will set a `nodeType` filter with the specified node ids.
+
+#### Setting a `rawFilter`
+
+!!! warning annotate "Use it on your own risk!"
+    The **NEAT** team is not responsible for any issues that may arise from setting a raw filter. This includes **NEAT** errors, **CDF** errors,  performance issues, etc. We do not recommend setting a raw filter unless you know what you are doing.
+
+If the above filters are limiting and you have no other choice you can set a raw filter. The syntax is as follows:
+
+* `rawFilter(your_custom_filter_as_json_string)` - This will set a raw filter with the specified filter.
+
+In this example of the raw filter:
+
+```
+rawFilter({"equals": {"property": ["node", "type"], "value": {"space": "power", "externalId": "WindTurbine"}}})
+```
+
+the JSON string that defines filter is:
+
+```JSON
+{"equals": {"property": ["node", "type"], "value": {"space": "power", "externalId": "WindTurbine"}}}
+```
+
+BEWARE to properly form the JSON string, as it is easy to make mistakes. The JSON string must be a valid JSON object!
+
+The exemplary `Rules` sheet with the above filters can be downloaded using [this link](../artifacts/rules/dms-architect-rules-raw-filter-example.xlsx).

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "cognite-neat"
-version = "0.77.5"
+version = "0.77.6"
 readme = "README.md"
 description = "Knowledge graph transformation"
 authors = [

tests/tests_unit/rules/test_models/test_wrapped_entities.py

@@ -3,6 +3,7 @@
 import pytest
 from cognite.client import data_modeling as dm
 
+from cognite.neat.rules import importers
 from cognite.neat.rules.models.entities import ContainerEntity, DMSNodeEntity
 from cognite.neat.rules.models.wrapped_entities import (
     DMSFilter,
@@ -11,6 +12,7 @@
     RawFilter,
     WrappedEntity,
 )
+from tests import config
 
 RAW_FILTER_EXAMPLE = """{"and": [
     {
@@ -115,3 +117,13 @@ def test_has_data_vs_raw_filter(self) -> None:
             .as_dms_filter()
             .dump()
         )
+
+    def test_raw_filter_in_sheet(self) -> None:
+        rules, issues = importers.ExcelImporter(
+            config.DOC_RULES / "dms-architect-rules-raw-filter-example.xlsx"
+        ).to_rules()
+
+        assert rules.views.data[0].filter_ == RawFilter.load(
+            """rawFilter({"equals": {"property": ["node", "type"],
+                "value": {"space": "power", "externalId": "WindTurbine"}}})"""
+        )