OARec: facets and distributed search updates

Author: tomkralidis

pycsw/ogc/api/oapi.py

@@ -101,6 +101,10 @@ def gen_oapi(config, oapi_filepath, mode='ogcapi-records'):
                 'description': 'a reference to the formal definition of the type',  # noqa
                 'format': 'url',
                 'type': 'string'
+            },
+            'facet': {
+                'description': 'whether the queryable is also a facet',
+                'type': 'boolean'
             }
         },
         'required': [
@@ -109,6 +113,75 @@ def gen_oapi(config, oapi_filepath, mode='ogcapi-records'):
         ],
         'type': 'object'
     }
+    oapi['components']['schemas']['queryables'] = {
+        'properties': {
+            'id': {
+                'type': 'string',
+                'description': 'collection identifier'
+            },
+            'title': {
+                'type': 'string',
+                'description': 'collection title'
+            },
+            'queryables2': {
+                'items': {
+                    '$ref': '#/components/schemas/queryable'
+                },
+                'type': 'array'
+            }
+        },
+        'required': [
+            'queryables'
+        ],
+        'type': 'object'
+    }
+
+    oapi['components']['responses']['Facets'] = {
+        'content': {
+            'application/facets+json': {
+                'schema': {
+                    '$ref': '#/components/schemas/facets'
+                }
+            }
+        },
+        'description': 'successful facets operation'
+    }
+    oapi['components']['schemas']['facets'] = {
+        'type': 'object',
+        'properties': {
+            'id': {
+                'type': 'string',
+                'description': 'collection identifier'
+            },
+            'title': {
+                'type': 'string',
+                'description': 'collection title'
+            },
+            'facets': {
+                'type': 'object',
+                'patternProperties': {
+                    '^.*': {
+                        'type': 'object',
+                        'properties': {
+                            'type': {
+                                'type': 'string',
+                                'enum': [
+                                    'term',
+                                    'histogram',
+                                    'filter'
+                                ]
+                            },
+                            'property': {
+                                'type': 'string',
+                                'description': 'property name'
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    }
+
     oapi['components']['schemas']['queryables'] = {
         'properties': {
             'queryables': {
@@ -388,6 +461,30 @@ def gen_oapi(config, oapi_filepath, mode='ogcapi-records'):
     }
 
     oapi['paths']['/collections/{collectionId}/queryables'] = path2
+
+    path = {
+        'get': {
+            'tags': ['Facets'],
+            'summary': 'Facets page',
+            'description': 'Facets page',
+            'operationId': 'getFacets',
+            'parameters': [
+                {'$ref': '#/components/parameters/f'},
+                {'$ref': '#/components/parameters/collectionId'}
+            ],
+            'responses': {
+                '200': {
+                    '$ref': '#/components/responses/Facets'
+                },
+                '500': {
+                    '$ref': '#/components/responses/ServerError'
+                }
+            }
+        }
+    }
+
+    oapi['paths']['/collections/{collectionId}/facets'] = path
+
     oapi['components']['parameters']['collectionId']['default'] = 'metadata:main'  # noqa
 
     path = {
@@ -419,18 +516,19 @@ def gen_oapi(config, oapi_filepath, mode='ogcapi-records'):
             'summary': 'Federated catalogs page',
             'description': 'Federated catalogs page',
             'operationId': 'getFederatedCatalog',
-            'parameters': [
-                {'$ref': '#/components/parameters/collectionId'},
-                {'name': 'catalogId',
-                 'in': 'path',
-                 'description': 'catalog ID',
-                 'required': True,
-                 'schema': {
+            'parameters': [{
+                '$ref': '#/components/parameters/collectionId'
+            }, {
+                'name': 'catalogId',
+                'in': 'path',
+                'description': 'catalog ID',
+                'required': True,
+                'schema': {
                      'type': 'string'
                  }
-                },
-                {'$ref': '#/components/parameters/f'}
-            ],
+            }, {
+                '$ref': '#/components/parameters/f'
+            }],
             'responses': {
                 '200': {
                     '$ref': '#/components/responses/FederatedCatalog'
@@ -442,7 +540,7 @@ def gen_oapi(config, oapi_filepath, mode='ogcapi-records'):
         }
     }
 
-    oapi['paths']['/collections/{collectionId}/federatedCatalogs/{catalogId}'] = path
+    oapi['paths']['/collections/{collectionId}/federatedCatalogs/{catalogId}'] = path  # noqa
 
     path = {
         'get': {

pycsw/ogc/api/records.py

@@ -76,6 +76,8 @@
     'http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/sorting',
     'http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/json',
     'http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/html',
+    'http://www.opengis.net/spec/ogcapi-records-2/1.0/conf/simple',
+    'http://www.opengis.net/spec/ogcapi-records-4/1.0/conf/federated-search',
     'http://www.opengis.net/spec/cql2/1.0/conf/cql2-json',
     'http://www.opengis.net/spec/cql2/1.0/conf/cql2-text'
 ]
@@ -529,6 +531,8 @@ def queryables(self, headers_, args, collection='metadata:main'):
         for key, value in properties.items():
             if key in self.repository.query_mappings or key == 'geometry':
                 properties2[key] = value
+                if key in self.facets:
+                    properties2[key]['facet'] = True
 
         if collection == 'metadata:main':
             title = self.config['metadata']['identification']['title']
@@ -548,6 +552,53 @@ def queryables(self, headers_, args, collection='metadata:main'):
 
         return self.get_response(200, headers_, response, 'queryables.html')
 
+    def facets_(self, headers_, args, collection='metadata:main'):
+        """
+        Provide collection facets
+
+        :param headers_: copy of HEADERS object
+        :param args: request parameters
+        :param collection: name of collection
+
+        :returns: tuple of headers, status code, content
+        """
+
+        facets_ = {}
+        headers_['Content-Type'] = self.get_content_type(headers_, args)
+
+        if 'json' in headers_['Content-Type']:
+            headers_['Content-Type'] = 'application/facets+json'
+
+        if collection not in self.get_collections(collection=collection):
+            msg = 'Invalid collection'
+            LOGGER.exception(msg)
+            return self.get_exception(400, headers_, 'InvalidParameterValue', msg)
+
+        for value in self.config['repository']['facets']:
+            facets_[value] = {
+                'type': 'term',
+                'property': value,
+                'sortedBy': 'count'
+            }
+
+        if collection == 'metadata:main':
+            title = self.config['metadata']['identification']['title']
+        else:
+            title = self.config['metadata']['identification']['title']
+            virtual_collection = self.repository.query_ids([collection])[0]
+            title = virtual_collection.title
+
+        response = {
+            'id': collection,
+            'type': 'object',
+            'title': title,
+            'facets': facets_,
+            '$schema': 'http://json-schema.org/draft/2019-09/schema',
+            '$id': f"{self.config['server']['url']}/collections/{collection}/facets"
+        }
+
+        return self.get_response(200, headers_, response, 'facets.html')
+
     def items(self, headers_, json_post_data, args, collection='metadata:main'):
         """
         Provide collection items
@@ -818,6 +869,7 @@ def items(self, headers_, json_post_data, args, collection='metadata:main'):
         distributed = str2bool(args.get('distributedsearch', False))
 
         if distributed:
+            args.pop('distributedsearch')
             distributed_search = self.config.get('distributedsearch', {})
             merge_results = distributed_search.get('merge_results', False)
 
@@ -833,7 +885,6 @@ def items(self, headers_, json_post_data, args, collection='metadata:main'):
                 }
                 try:
                     w = Records(fc_url)
-                    args.pop('distributedsearch')
                     fc_results = w.collection_items(fc_collection, **args)
                     for feature in fc_results['features']:
                         if merge_results:
@@ -849,6 +900,8 @@ def items(self, headers_, json_post_data, args, collection='metadata:main'):
                 for key, value in fsrs.items():
                     response['features'].extend(value['features'])
 
+            args['distributedSearch'] = 'true'
+
         LOGGER.debug('Creating links')
 
         link_args = {**args}

pycsw/templates/collection.html

@@ -35,6 +35,7 @@ <h2>{{ data['title'] }}</h2>
         <td>
            <a title="items" href="{{ config['server']['url'] }}/collections/{{ data.id }}/items">items</a>
            <a title="queryables" href="{{ config['server']['url'] }}/collections/{{ data.id }}/queryables">queryables</a>
+           <a title="facets" href="{{ config['server']['url'] }}/collections/{{ data.id }}/facets">facets</a>
            {% if data.id == 'metadata:main' and config['distributedsearch'] %}
            <a title="federated catalogs" href="{{ config['server']['url'] }}/collections/{{ data.id }}/federatedCatalogs">federated catalogs</a>
            {% endif %}

pycsw/templates/collections.html

@@ -34,6 +34,7 @@ <h2>Collections</h2>
         <td>
            <a title="items" href="{{ config['server']['url'] }}/collections/{{ col.id }}/items">items</a>
            <a title="queryables" href="{{ config['server']['url'] }}/collections/{{ col.id }}/queryables">queryables</a>
+           <a title="facets" href="{{ config['server']['url'] }}/collections/{{ col.id }}/facets">facets</a>
            {% if col.id == 'metadata:main' and config['distributedsearch'] %}
            <a title="federated catalogs" href="{{ config['server']['url'] }}/collections/{{ col.id }}/federatedCatalogs">federated catalogs</a>
            {% endif %}

pycsw/templates/facets.html

@@ -0,0 +1,56 @@
+{% extends "_base.html" %}
+{% block title %}{{ super() }} Facets {% endblock %}
+
+{% block crumbs %}
+{{ super() }} /
+<a href="{{ config['server']['url'] }}/collections">Collections</a> /
+<a href="{{ config['server']['url'] }}/collections/{{ data['id'] }}">{{ data['title'] }}</a> /
+<a href="{{ config['server']['url'] }}/collections/{{ data['id'] }}/facets">Facets</a>
+{% endblock %}
+
+{% block body %}
+
+<section id="queryables">
+  <h2>Facets</h2>
+  <h2>{{ data['title'] }}</h2>
+
+  <table class="table table-striped table-hover">
+    <thead>
+      <tr>
+        <th>Name</th>
+        <th>Type</th>
+        <th>Facet</th>
+      </tr>
+    </thead>
+    <tbody>
+      {% for qname, qinfo in data['facets'].items() %}
+      {% if qname == 'geometry' %}
+      <tr>
+        <td colspan="3"><a href="{{ qinfo['$ref'] }}">{{ qname }}</a></td>
+      </tr>
+      {% else %}
+      <tr>
+        <td>{{ qname }}</td>
+        <td>
+          <code>{{ qinfo['type'] }}</code>
+          {% if 'enum' in qinfo %}
+          <ul>
+            {% for value in qinfo['enum'] %}
+            <li><i>{{ value }}</i></li>
+            {% endfor %}
+          </ul>
+          {% endif %}
+        </td>
+        {% if qname in config['repository'].get('facets', []) %}
+        <td>true</td>
+        {% else %}
+        <td></td>
+        {% endif %}
+      </tr>
+      {% endif %}
+      {% endfor %}
+    </tbody>
+  </table>
+</section>
+
+{% endblock %}

pycsw/templates/queryables.html

@@ -19,13 +19,14 @@ <h2>{{ data['title'] }}</h2>
       <tr>
         <th>Name</th>
         <th>Type</th>
+        <th>Facet</th>
       </tr>
     </thead>
     <tbody>
       {% for qname, qinfo in data['properties'].items() %}
       {% if qname == 'geometry' %}
       <tr>
-        <td colspan="2"><a href="{{ qinfo['$ref'] }}">{{ qname }}</a></td>
+        <td colspan="3"><a href="{{ qinfo['$ref'] }}">{{ qname }}</a></td>
       </tr>
       {% else %}
       <tr>
@@ -40,6 +41,11 @@ <h2>{{ data['title'] }}</h2>
           </ul>
           {% endif %}
         </td>
+        {% if qname in config['repository'].get('facets', []) %}
+        <td>true</td>
+        {% else %}
+        <td></td>
+        {% endif %}
       </tr>
       {% endif %}
       {% endfor %}

pycsw/wsgi_flask.py

@@ -206,6 +206,20 @@ def queryables(collection='metadata:main'):
                             collection))
 
 
+@BLUEPRINT.route('/collections/<collection>/facets')
+def facets(collection='metadata:main'):
+    """
+    OGC API collection facets endpoint
+
+    :param collection: collection name
+
+    :returns: HTTP response
+    """
+
+    return get_response(api_.facets_(dict(request.headers), request.args,
+                        collection))
+
+
 @BLUEPRINT.route('/collections/<collection>/federatedCatalogs')
 def federated_catalogues(collection='metadata:main'):
     """

tests/functionaltests/suites/oarec/conftest.py

@@ -4,7 +4,7 @@
 #          Tom Kralidis <tomkralidis@gmail.com>
 #
 # Copyright (c) 2023 Ricardo Garcia Silva
-# Copyright (c) 2024 Tom Kralidis
+# Copyright (c) 2026 Tom Kralidis
 #
 # Permission is hereby granted, free of charge, to any person
 # obtaining a copy of this software and associated documentation
@@ -111,7 +111,10 @@ def config():
         },
         'repository': {
             'database': 'sqlite:///tests/functionaltests/suites/cite/data/cite.db',  # noqa
-            'table': 'records'
+            'table': 'records',
+            'facets': [
+                'type'
+            ]
         }
     }