feat: add parameter to support both AND and OR combinations of tags_filter.

Author: 01100100

quackosm/functions.py

@@ -51,6 +51,7 @@ def convert_pbf_to_duckdb(
     ignore_cache: bool = False,
     filter_osm_ids: Optional[list[str]] = None,
     custom_sql_filter: Optional[str] = None,
+    filter_logical_operator: str = "OR",
     duckdb_table_name: str = "quackosm",
     working_directory: Union[str, Path] = "files",
     osm_way_polygon_features_config: Optional[Union[OsmWayPolygonConfig, dict[str, Any]]] = None,
@@ -108,6 +109,10 @@ def convert_pbf_to_duckdb(
         custom_sql_filter (str, optional): Allows users to pass custom SQL conditions used
             to filter OSM features. It will be embedded into predefined queries and requires
             DuckDB syntax to operate on tags map object. Defaults to None.
+        filter_logical_operator (str, optional): Logical operator used to join positive tag filter
+            conditions. Either "OR" (default) or "AND". With "OR", objects matching any
+            of the tag conditions are included. With "AND", objects must match all tag
+            conditions. Defaults to "OR".
         duckdb_table_name (str): Table in which to store the OSM data inside the DuckDB database.
         working_directory (Union[str, Path], optional): Directory where to save
             the parsed `*.parquet` files. Defaults to "files".
@@ -269,6 +274,7 @@ def convert_pbf_to_duckdb(
         tags_filter=tags_filter,
         geometry_filter=geometry_filter,
         custom_sql_filter=custom_sql_filter,
+        filter_logical_operator=filter_logical_operator,
         working_directory=working_directory,
         osm_way_polygon_features_config=osm_way_polygon_features_config,
         compression=compression,
@@ -306,6 +312,7 @@ def convert_geometry_to_duckdb(
     ignore_cache: bool = False,
     filter_osm_ids: Optional[list[str]] = None,
     custom_sql_filter: Optional[str] = None,
+    filter_logical_operator: str = "OR",
     duckdb_table_name: str = "quackosm",
     working_directory: Union[str, Path] = "files",
     osm_way_polygon_features_config: Optional[Union[OsmWayPolygonConfig, dict[str, Any]]] = None,
@@ -368,6 +375,10 @@ def convert_geometry_to_duckdb(
         custom_sql_filter (str, optional): Allows users to pass custom SQL conditions used
             to filter OSM features. It will be embedded into predefined queries and requires
             DuckDB syntax to operate on tags map object. Defaults to None.
+        filter_logical_operator (str, optional): Logical operator used to join positive tag filter
+            conditions. Either "OR" (default) or "AND". With "OR", objects matching any
+            of the tag conditions are included. With "AND", objects must match all tag
+            conditions. Defaults to "OR".
         duckdb_table_name (str): Table in which to store the OSM data inside the DuckDB database.
         working_directory (Union[str, Path], optional): Directory where to save
             the parsed `*.parquet` files. Defaults to "files".
@@ -492,6 +503,7 @@ def convert_geometry_to_duckdb(
         tags_filter=tags_filter,
         geometry_filter=geometry_filter,
         custom_sql_filter=custom_sql_filter,
+        filter_logical_operator=filter_logical_operator,
         working_directory=working_directory,
         osm_way_polygon_features_config=osm_way_polygon_features_config,
         compression=compression,
@@ -532,6 +544,7 @@ def convert_osm_extract_to_duckdb(
     ignore_cache: bool = False,
     filter_osm_ids: Optional[list[str]] = None,
     custom_sql_filter: Optional[str] = None,
+    filter_logical_operator: str = "OR",
     duckdb_table_name: str = "quackosm",
     working_directory: Union[str, Path] = "files",
     osm_way_polygon_features_config: Optional[Union[OsmWayPolygonConfig, dict[str, Any]]] = None,
@@ -592,6 +605,10 @@ def convert_osm_extract_to_duckdb(
         custom_sql_filter (str, optional): Allows users to pass custom SQL conditions used
             to filter OSM features. It will be embedded into predefined queries and requires
             DuckDB syntax to operate on tags map object. Defaults to None.
+        filter_logical_operator (str, optional): Logical operator used to join positive tag filter
+            conditions. Either "OR" (default) or "AND". With "OR", objects matching any
+            of the tag conditions are included. With "AND", objects must match all tag
+            conditions. Defaults to "OR".
         duckdb_table_name (str): Table in which to store the OSM data inside the DuckDB database.
         working_directory (Union[str, Path], optional): Directory where to save
             the parsed `*.parquet` files. Defaults to "files".
@@ -672,6 +689,7 @@ def convert_osm_extract_to_duckdb(
         tags_filter=tags_filter,
         geometry_filter=geometry_filter,
         custom_sql_filter=custom_sql_filter,
+        filter_logical_operator=filter_logical_operator,
         working_directory=working_directory,
         osm_way_polygon_features_config=osm_way_polygon_features_config,
         compression=compression,
@@ -709,6 +727,7 @@ def convert_pbf_to_parquet(
     ignore_cache: bool = False,
     filter_osm_ids: Optional[list[str]] = None,
     custom_sql_filter: Optional[str] = None,
+    filter_logical_operator: str = "OR",
     working_directory: Union[str, Path] = "files",
     osm_way_polygon_features_config: Optional[Union[OsmWayPolygonConfig, dict[str, Any]]] = None,
     save_as_wkt: bool = False,
@@ -766,6 +785,10 @@ def convert_pbf_to_parquet(
         custom_sql_filter (str, optional): Allows users to pass custom SQL conditions used
             to filter OSM features. It will be embedded into predefined queries and requires
             DuckDB syntax to operate on tags map object. Defaults to None.
+        filter_logical_operator (str, optional): Logical operator used to join positive tag filter
+            conditions. Either "OR" (default) or "AND". With "OR", objects matching any
+            of the tag conditions are included. With "AND", objects must match all tag
+            conditions. Defaults to "OR".
         working_directory (Union[str, Path], optional): Directory where to save
             the parsed `*.parquet` files. Defaults to "files".
         osm_way_polygon_features_config (Union[OsmWayPolygonConfig, dict[str, Any]], optional):
@@ -927,6 +950,7 @@ def convert_pbf_to_parquet(
         tags_filter=tags_filter,
         geometry_filter=geometry_filter,
         custom_sql_filter=custom_sql_filter,
+        filter_logical_operator=filter_logical_operator,
         working_directory=working_directory,
         osm_way_polygon_features_config=osm_way_polygon_features_config,
         compression=compression,
@@ -964,6 +988,7 @@ def convert_geometry_to_parquet(
     ignore_cache: bool = False,
     filter_osm_ids: Optional[list[str]] = None,
     custom_sql_filter: Optional[str] = None,
+    filter_logical_operator: str = "OR",
     working_directory: Union[str, Path] = "files",
     osm_way_polygon_features_config: Optional[Union[OsmWayPolygonConfig, dict[str, Any]]] = None,
     save_as_wkt: bool = False,
@@ -1026,6 +1051,10 @@ def convert_geometry_to_parquet(
         custom_sql_filter (str, optional): Allows users to pass custom SQL conditions used
             to filter OSM features. It will be embedded into predefined queries and requires
             DuckDB syntax to operate on tags map object. Defaults to None.
+        filter_logical_operator (str, optional): Logical operator used to join positive tag filter
+            conditions. Either "OR" (default) or "AND". With "OR", objects matching any
+            of the tag conditions are included. With "AND", objects must match all tag
+            conditions. Defaults to "OR".
         working_directory (Union[str, Path], optional): Directory where to save
             the parsed `*.parquet` files. Defaults to "files".
         osm_way_polygon_features_config (Union[OsmWayPolygonConfig, dict[str, Any]], optional):
@@ -1149,6 +1178,7 @@ def convert_geometry_to_parquet(
         tags_filter=tags_filter,
         geometry_filter=geometry_filter,
         custom_sql_filter=custom_sql_filter,
+        filter_logical_operator=filter_logical_operator,
         working_directory=working_directory,
         osm_way_polygon_features_config=osm_way_polygon_features_config,
         compression=compression,
@@ -1189,6 +1219,7 @@ def convert_osm_extract_to_parquet(
     ignore_cache: bool = False,
     filter_osm_ids: Optional[list[str]] = None,
     custom_sql_filter: Optional[str] = None,
+    filter_logical_operator: str = "OR",
     working_directory: Union[str, Path] = "files",
     osm_way_polygon_features_config: Optional[Union[OsmWayPolygonConfig, dict[str, Any]]] = None,
     save_as_wkt: bool = False,
@@ -1249,6 +1280,10 @@ def convert_osm_extract_to_parquet(
         custom_sql_filter (str, optional): Allows users to pass custom SQL conditions used
             to filter OSM features. It will be embedded into predefined queries and requires
             DuckDB syntax to operate on tags map object. Defaults to None.
+        filter_logical_operator (str, optional): Logical operator used to join positive tag filter
+            conditions. Either "OR" (default) or "AND". With "OR", objects matching any
+            of the tag conditions are included. With "AND", objects must match all tag
+            conditions. Defaults to "OR".
         working_directory (Union[str, Path], optional): Directory where to save
             the parsed `*.parquet` files. Defaults to "files".
         osm_way_polygon_features_config (Union[OsmWayPolygonConfig, dict[str, Any]], optional):
@@ -1330,6 +1365,7 @@ def convert_osm_extract_to_parquet(
         tags_filter=tags_filter,
         geometry_filter=geometry_filter,
         custom_sql_filter=custom_sql_filter,
+        filter_logical_operator=filter_logical_operator,
         working_directory=working_directory,
         osm_way_polygon_features_config=osm_way_polygon_features_config,
         compression=compression,
@@ -1367,6 +1403,7 @@ def convert_pbf_to_geodataframe(
     ignore_cache: bool = False,
     filter_osm_ids: Optional[list[str]] = None,
     custom_sql_filter: Optional[str] = None,
+    filter_logical_operator: str = "OR",
     working_directory: Union[str, Path] = "files",
     osm_way_polygon_features_config: Optional[Union[OsmWayPolygonConfig, dict[str, Any]]] = None,
     verbosity_mode: VERBOSITY_MODE = "transient",
@@ -1423,6 +1460,10 @@ def convert_pbf_to_geodataframe(
         custom_sql_filter (str, optional): Allows users to pass custom SQL conditions used
             to filter OSM features. It will be embedded into predefined queries and requires
             DuckDB syntax to operate on tags map object. Defaults to None.
+        filter_logical_operator (str, optional): Logical operator used to join positive tag filter
+            conditions. Either "OR" (default) or "AND". With "OR", objects matching any
+            of the tag conditions are included. With "AND", objects must match all tag
+            conditions. Defaults to "OR".
         working_directory (Union[str, Path], optional): Directory where to save
             the parsed `*.parquet` files. Defaults to "files".
         osm_way_polygon_features_config (Union[OsmWayPolygonConfig, dict[str, Any]], optional):
@@ -1558,6 +1599,7 @@ def convert_pbf_to_geodataframe(
         tags_filter=tags_filter,
         geometry_filter=geometry_filter,
         custom_sql_filter=custom_sql_filter,
+        filter_logical_operator=filter_logical_operator,
         working_directory=working_directory,
         osm_way_polygon_features_config=osm_way_polygon_features_config,
         compression=compression,
@@ -1591,6 +1633,7 @@ def convert_geometry_to_geodataframe(
     ignore_cache: bool = False,
     filter_osm_ids: Optional[list[str]] = None,
     custom_sql_filter: Optional[str] = None,
+    filter_logical_operator: str = "OR",
     working_directory: Union[str, Path] = "files",
     osm_way_polygon_features_config: Optional[Union[OsmWayPolygonConfig, dict[str, Any]]] = None,
     verbosity_mode: VERBOSITY_MODE = "transient",
@@ -1649,6 +1692,10 @@ def convert_geometry_to_geodataframe(
         custom_sql_filter (str, optional): Allows users to pass custom SQL conditions used
             to filter OSM features. It will be embedded into predefined queries and requires
             DuckDB syntax to operate on tags map object. Defaults to None.
+        filter_logical_operator (str, optional): Logical operator used to join positive tag filter
+            conditions. Either "OR" (default) or "AND". With "OR", objects matching any
+            of the tag conditions are included. With "AND", objects must match all tag
+            conditions. Defaults to "OR".
         working_directory (Union[str, Path], optional): Directory where to save
             the parsed `*.parquet` files. Defaults to "files".
         osm_way_polygon_features_config (Union[OsmWayPolygonConfig, dict[str, Any]], optional):
@@ -1729,6 +1776,7 @@ def convert_geometry_to_geodataframe(
         tags_filter=tags_filter,
         geometry_filter=geometry_filter,
         custom_sql_filter=custom_sql_filter,
+        filter_logical_operator=filter_logical_operator,
         working_directory=working_directory,
         osm_way_polygon_features_config=osm_way_polygon_features_config,
         compression=compression,
@@ -1765,6 +1813,7 @@ def convert_osm_extract_to_geodataframe(
     ignore_cache: bool = False,
     filter_osm_ids: Optional[list[str]] = None,
     custom_sql_filter: Optional[str] = None,
+    filter_logical_operator: str = "OR",
     working_directory: Union[str, Path] = "files",
     osm_way_polygon_features_config: Optional[Union[OsmWayPolygonConfig, dict[str, Any]]] = None,
     verbosity_mode: VERBOSITY_MODE = "transient",
@@ -1821,6 +1870,10 @@ def convert_osm_extract_to_geodataframe(
         custom_sql_filter (str, optional): Allows users to pass custom SQL conditions used
             to filter OSM features. It will be embedded into predefined queries and requires
             DuckDB syntax to operate on tags map object. Defaults to None.
+        filter_logical_operator (str, optional): Logical operator used to join positive tag filter
+            conditions. Either "OR" (default) or "AND". With "OR", objects matching any
+            of the tag conditions are included. With "AND", objects must match all tag
+            conditions. Defaults to "OR".
         working_directory (Union[str, Path], optional): Directory where to save
             the parsed `*.parquet` files. Defaults to "files".
         osm_way_polygon_features_config (Union[OsmWayPolygonConfig, dict[str, Any]], optional):
@@ -1892,6 +1945,7 @@ def convert_osm_extract_to_geodataframe(
         tags_filter=tags_filter,
         geometry_filter=geometry_filter,
         custom_sql_filter=custom_sql_filter,
+        filter_logical_operator=filter_logical_operator,
         working_directory=working_directory,
         osm_way_polygon_features_config=osm_way_polygon_features_config,
         compression=compression,

quackosm/pbf_file_reader.py

@@ -143,6 +143,7 @@ def __init__(
         tags_filter: Optional[Union[OsmTagsFilter, GroupedOsmTagsFilter]] = None,
         geometry_filter: Optional[BaseGeometry] = None,
         custom_sql_filter: Optional[str] = None,
+        filter_logical_operator: str = "OR",
         working_directory: Union[str, Path] = "files",
         osm_way_polygon_features_config: Optional[
             Union[OsmWayPolygonConfig, dict[str, Any]]
@@ -177,6 +178,10 @@ def __init__(
             custom_sql_filter (str, optional): Allows users to pass custom SQL conditions used
                 to filter OSM features. It will be embedded into predefined queries and requires
                 DuckDB syntax to operate on tags map object. Defaults to `None`.
+            filter_logical_operator (str, optional): Logical operator used to join positive tag
+                filter conditions. Either "OR" (default) or "AND". With "OR", objects matching any
+                of the tag conditions are included. With "AND", objects must match all tag
+                conditions. Defaults to "OR".
             working_directory (Union[str, Path], optional): Directory where to save
                 the parsed `*.parquet` files. Defaults to "files".
             osm_way_polygon_features_config (Union[OsmWayPolygonConfig, dict[str, Any]], optional):
@@ -229,6 +234,9 @@ def __init__(
         self.merged_tags_filter: Optional[Union[GroupedOsmTagsFilter, OsmTagsFilter]] = None
 
         self.custom_sql_filter = custom_sql_filter
+        self.filter_logical_operator = filter_logical_operator.upper()
+        if self.filter_logical_operator not in ("OR", "AND"):
+            raise ValueError("filter_logical_operator must be either 'OR' or 'AND'")
 
         self.geometry_coverage_iou_threshold = geometry_coverage_iou_threshold
         self.allow_uncovered_geometry = allow_uncovered_geometry
@@ -1809,7 +1817,7 @@ def _generate_osm_tags_sql_filter(self) -> str:
         if not positive_filter_clauses:
             positive_filter_clauses.append("(1=1)")
 
-        joined_filter_clauses = " OR ".join(positive_filter_clauses)
+        joined_filter_clauses = f" {self.filter_logical_operator} ".join(positive_filter_clauses)
         if negative_filter_clauses:
             joined_filter_clauses = (
                 f"({joined_filter_clauses}) AND ({' AND '.join(negative_filter_clauses)})"