Posted Feb 25 by Peng Qiu.
Updated Feb 26.

This tutorial is the second post of the Search Services Series in Documentum REST Services.

Last activity Feb 26 by Peng Qiu.
59 views. 0 comments.

Overview

This tutorial is the second post of the Search Services Series in Documentum REST Services. Advanced facets is worth a separate tutorial even though it is part of AQL. In Documentum REST 7.2, users can only execute faceted search against one attribute, which is quite limited for many user scenarios. It has been improved a lot since Documentum REST 7.3 with AQL support.

Part 1. Advanced Searches in Documentum REST Services (1): AQL
Part 2. Advanced Searches in Documentum REST Services (2): Facets
Part 3. Advanced Searches in Documentum REST Services (3): Saved Searches
Part 4. Advanced Searches in Documentum REST Services (4): Search Templates

Preliminary

Please refer to the Preliminary section in Advanced Searches in Documentum REST Services (1): AQL to prepare the environment.

Multiple Facets

Sometimes users want to get facets against more than one attributes for one search, which is called multiple facets, e.g. both color and size for clothes. Here is an example of facet attributes for SysObject type. There are two facet definitions here, which group the search results at the same level.

  • one for attribute r_full_content_size
  • one for attribute keywords

Below is the POST request to execute the facet search. The request body is an AQL with the facet definition.

POST http://localhost:8080/dctm-rest/repositories/REPO1/search?include-total=true
Content-Type: application/json

{
    "facet-definitions": [
        {
            "id": "id1",
            "attributes": ["r_full_content_size"],
            "group-by": "range",
            "properties": {
                "range": "10000:20000, 40000:90000"   
            }
        },
        {
            "id": "id2",
            "attributes": ["keywords"]
        }
    ]
}

Here is the explanation of the above facet definition in the AQL request:

  • The facet definition for attribute r_full_content_size defines a group-by strategy with range. This is the new capability brought by AQL. Other strategies can be string (the default one), range, alphrange, day, week, relativeDate, etc. In this sample, results are grouped in two ranges 10k-20k, and 40k-90k.
  • The facet definition for attribute keywords defines a string value strategy (default).
  • The two definitions group the search result independently, and do not impact to each other, so they are
    called multiple facets or parallel facets.

The multiple facets results have several facets on the same level.

{
    "id": "http://localhost:8080/dctm-rest/repositories/REPO1/search",
    "title": "Search results",
    ...
    "facets": [
        {
            "facet-id": "id1",
            "facet-label": "Full Content Size",
            "facet-value": [
                {
                    "facet-id": "id1",
                    "facet-value-id": "40000:90000",
                    "facet-value-count": 6,
                    "facet-value-constraint": "40000/90000",
                    "link": {
                        "rel": "search",
                        "href": "http://localhost:8080/dctm-rest/repositories/REPO1/search?facet-id-constraints=id1%3D40000/90000"
                    }
                },
                {
                    "facet-id": "id1",
                    "facet-value-id": "10000:20000",
                    "facet-value-count": 0,
                    "facet-value-constraint": "10000/20000",
                    "link": {
                        "rel": "search",
                        "href": "http://localhost:8080/dctm-rest/repositories/REPO1/search?facet-id-constraints=id1%3D10000/20000"
                    }
                }
            ]
        },
        {
            "facet-id": "id2",
            "facet-label": "Keywords",
            "facet-value": [
                {
                    "facet-id": "id2",
                    "facet-value-id": "extensibility",
                    "facet-value-count": 3,
                    "facet-value-constraint": "extensibility",
                    "link": {
                        "rel": "search",
                        "href": "http://localhost:8080/dctm-rest/repositories/REPO1/search?facet-id-constraints=id2%3Dextensibility"
                    }
                },
                {
                    "facet-id": "id2",
                    "facet-value-id": "client",
                    "facet-value-count": 1,
                    "facet-value-constraint": "client",
                    "link": {
                        "rel": "search",
                        "href": "http://localhost:8080/dctm-rest/repositories/REPO1/search?facet-id-constraints=id2%3Dclient"
                    }
                },
                {
                    "facet-id": "id2",
                    "facet-value-id": "search",
                    "facet-value-count": 1,
                    "facet-value-constraint": "search",
                    "link": {
                        "rel": "search",
                        "href": "http://localhost:8080/dctm-rest/repositories/REPO1/search?facet-id-constraints=id2%3Dsearch"
                    }
                }
            ]
        }
    ]
}

Hierarchical Facets

The hierarchical facets contain more than one attributes, too.But these attributes are not at the same level. More precisely, they are hierarchical. A similar hierarchical sample that helps to understand the hierarchical facets is geographical hierarchy: continents - continental sections - countries - cities…

In the tutorial, we will continue with the content size and keywords sample. Here is a POST request to execute the search service and the request body contains the hierarchical facet definitions.

POST http://localhost:8080/dctm-rest/repositories/REPO1/search?include-total=true
Content-Type: application/json

{
    "facet-definitions": [
        {
           "id": "id1",
               "attributes": ["r_full_content_size"],
               "group-by": "range",
               "properties": {
                   "range": "10000:20000, 40000:90000"    
               },
               "facet-definition": {
                "id": "id2",
                "attributes": ["keywords"]
            }
        }
    ]
}

Here is the explanation of the above facet definitions:

  • The search result is firstly grouped by the facet attribute r_full_content_size.
  • Each grouped result is then grouped by the facet attribute keywords.
  • The nested facet definition is depending on the grouped result of the parent facet definition, so called
    hierarchical facets or nested facets.

Below is the hierarchical facets results.

{
    "id": "http://localhost:8080/dctm-rest/repositories/REPO1/search",
    "title": "Search results",
    ...
    "facets": [
        {
            "facet-id": "id1",
            "facet-label": "Full Content Size",
            "facet-value": [
                {
                    "facet-id": "id1",
                    "facet-value-id": "40000:90000",
                    "facet-value-count": 6,
                    "facet-value-constraint": "40000/90000",
                    "link": {
                        "rel": "search",
                        "href": "http://localhost:8080/dctm-rest/repositories/REPO1/search?facet-id-constraints=id1%3D40000/90000"
                    },
                    "facets": [
                        {
                            "facet-id": "id2",
                            "facet-value-id": "extensibility",
                            "facet-value-count": 2,
                            "facet-value-constraint": "extensibility",
                            "link": {
                                "rel": "search",
                                "href": "http://localhost:8080/dctm-rest/repositories/REPO1/search?facet-id-constraints=id1%3D40000/90000,id2%3Dextensibility"
                            }
                        },
                        {
                            "facet-id": "id2",
                            "facet-value-id": "client",
                            "facet-value-count": 1,
                            "facet-value-constraint": "client",
                            "link": {
                                "rel": "search",
                                "href": "http://localhost:8080/dctm-rest/repositories/REPO1/search?facet-id-constraints=id1%3D40000/90000,id2%3Dclient"
                            }
                        }
                    ]
                },
                {
                    "facet-id": "id1",
                    "facet-value-id": "10000:20000",
                    "facet-value-count": 0,
                    "facet-value-constraint": "10000/20000",
                    "link": {
                        "rel": "search",
                        "href": "http://localhost:8080/dctm-rest/repositories/REPO1/search?facet-id-constraints=id1%3D10000/20000"
                    }
                }
            ]
        }
    ]
}   

Navigating Facets

The facet result does not return document items directly in the response, but instead, each facet result value has a URL link, which contains facet constraints for each group. For example, the link below extracted from the hierarchical facets sample has URL parameters and values:

facet-id-constraints=id1%3D40000/900000,id2%3Dclient

"link": {
    "rel": "search",
    "href": "http://localhost:8080/dctm-rest/repositories/REPO1/search?facet-id-constraints=id1%3D40000/90000,id2%3Dclient"
}

After a simple URL decoding, we can see its parameter value as

facet-id-constraints=id1=40000/90000,id2=client.

It is easy to find out that this is actually the facet constraints:

  • r_full_content_size(id1) is in range 40000 - 90000
  • keywords(id2) is client

But this URL doesn't contain search criteria so users can't navigate facets by just following it. It misses the search criteria because the length could be too large to construct the facet constraints into URL. The approach to navigate facets with AQL is to follow the link in facet results and POST the original search criteria.

The below request snippet makes a POST request to the href link of the specific facet result. The request body should be the original AQL. As expectation, there will be only one search result returned. Have a try!

POST http://localhost:8080/dctm-rest/repositories/REPO1/search?facet-id-constraints=id1%3D40000/90000,id2%3Dclient
Content-Type: application/json

{
    "facet-definitions": [
        {
        "id": "id1",
            "attributes": ["r_full_content_size"],
            "group-by": "range",
            "properties": {
                "range": "10000:20000, 40000:90000"    
            },
            "facet-definition": {
                "id": "id2",
                "attributes": ["keywords"]
            }
        }
    ] 
}

Conclusion

The article covers the basic knowledge about advanced facet search. By learning this topic, you get to know:

  • The facet search for more than one attributes is supported
  • Multiple facets, hierarchical facets and their differences
  • How to execute an advanced facet search
  • Use HTTP method POST to execute the facet search

NEXT: Part 3. Advanced Searches in Documentum REST Services (3): Saved Searches


Table of Contents

Your comment

To leave a comment, please sign in.