Customizing Predefined Queries

This section describes how to customize predefined queries used for simple and advanced search.

You can configure predefined queries in $INSTALLDIR/$ARCH/resources/PQDefinitions.json and load them using a dedicated script.

To add new predefined queries, create a new JSON file containing all your customizations and load it using the dedicated script.

Important: Follow this naming convention for PageObject and JSON files that you add to the updatePQ.bat|sh script:
  • PQsDefinitions_Custom for generic PageObject and input in updatePQ.bat|sh.
  • PQsDefinitionNLS_Custom_<ISO Code> for language-specific PageObject.

  1. On the 3DSpace Index server, create your JSON file in $INSTALLDIR/$ARCH/resources/
  2. Update the updatePQ.bat|sh script:
    1. Go to $INSTALLDIR/$ARCH.
    2. Add the path to the directory containing your new JSON file at the end of the script.

    Example:

    "d:\R2022x\Search\win_b64"\docs\javaserver\search_installutil.jar;
"d:\R2022x\Search\win_b64"\docs\javaserver\prefix_handler.jar;
"d:\R2022x\Search\win_b64"\cv\javabin\cv-sdk\cloudview-core-apis.jar;
"d:\R2022x\Search\win_b64"\cv\javabin\cv-sdk\cloudview-indexing-apis.jar;
"d:\R2022x\Search\win_b64"\cv\javabin\cv-sdk\security-java-api.jar;
"d:\R2022x\Search\win_b64"\cv\javabin\semantic\semantic.jar;
"d:\R2022x\Search\win_b64"\cv\javabin\edkcommons.jar;
"d:\R2022x\Search\win_b64"\cv\javabin\cv-sdk\mami-java-client.jar;
"d:\R2022x\Search\win_b64"\cv\javabin\cv-sdk\platform-base.jar;
"d:\R2022x\Search\win_b64"\cv\javabin\cloudview-java-plugin.jar;
"d:\R2022x\Search\win_b64"\cv\javabin\javax.json-1.0.4.jar;
"d:\R2022x\Search\win_b64"\cv\javabin\errorcodes.jar;
"d:\R2022x\Search\win_b64" com.matrixone.search.install.cloudview.PQUpdater d1037eno.dsone.3ds.com 26000 d:/temp/PQDefintions

    To configure the PQUpdater, choose one of the following options:

    Option Description
    com.matrixone.search.install.cloudview.PQUpdater <hostname> <baseport> In this case, the PQUpdaterlooks for the JSON files under the default directory, that is: $INSTALLDIR/$ARCH/resources
    com.matrixone.search.install.cloudview.PQUpdater <hostname> <baseport> <dir1>[,<dir2>,<dir3>...] You can also specify:
    • The default directory that contains JSON files. Pass the default directory as argument to the PQUpdater command.
      Note: The argument for default directory does not have to be <dir1>. It can be any of <dir1>, <dir2>, or <dir3>, provided it is mentioned in that list of directories.
    • And other directories that contain custom JSON files of Predefined Queries.

  3. Run the script updatePQ.bat|sh again.
  4. Create a generic PQsDefinitions_Custom PageObject in the 3DSpace.
    1. Save your PQs in a PQsDefinitions_Custom text file.
    2. Copy the file on the server, for example, under /home/data/RTV/<server_name>
    3. Run the following MQL commands: 

      add page PQsDefinitions_Custom;
modify page PQsDefinitions_Custom file /home/data/RTV/<server_name>/<your_PQ_filename>.txt;
print page PQsDefinitions_Custom; /* To verify if the page object is modified */

    Important: Always verify that your JSON file does not have syntax errors. You can use any online json validator.

  5. Create as many language-specific PageObject as required in the 3DSpace. For example, PQsDefinitionNLS_Custom_en (for English), PQsDefinitionNLS_Custom_fr (for French), etc.

    Their contents must reference the NLS of their respective PQIds. For example, 

    "Pqid1.Title":"NLS Of Customer PQ1"
"Pqid2.Title":"NLS Of Customer PQ2"
...

    1. Save your PQs in a PQsDefinitionNLS_Custom_<ISO Code> text file.
    2. Copy the file on the server, for example, under /home/data/RTV/<server_name>
    3. Run the following MQL commands: 

      add page PQsDefinitionNLS_Custom;
modify page PQsDefinitionNLS_Custom file /home/data/RTV/<server_name>/<your_PQ_NLS_filename>.txt;
print page PQsDefinitionNLS_Custom; /* To verify if the page object is modified */

    Notes:
    • Always verify that your JSON files do not have syntax errors. You can use any online json validator.
    • You must have the same PQs in these PageObjects, and give your json files as input to updatePQ.sh.

Predefined Queries Parameters

Property Mandatory Type Description
nbPQ Yes Integer Declares the number of PQ Objects in this resource/pageObject.
PQ Yes array of PQ Objects
abbreviations Yes String

Comma-separated list of abbreviations that users can enter in the 3DSearch App.

Each value must be unique globally (across all PQ Objects).

Important: Abbreviations are case-insensitive and must not contain any:
  • - (dash)
  • . (period)
  • ( (open parenthesis) and ) (close parenthesis)
  • & (ampersand)
id Yes Integer Unique Identifier, incrementally numbered.
pqid Yes String Unique PQ Identifier, also used to associate the PQ with its NLS resource.
value Yes String

UQL-based string, which is the expression to execute internally.

Important: The field names used in the expression must be in lowercase.

The user query input replaces all instances of the (__QUERY__) placeholder string in the expression.

Note: Always encapsulate the (__QUERY__) placeholder in brackets in your expressions.

Use \ to escape special characters, like quotes ".

To build this expression, you must understand your data model and its fields. For more information, see Installation and Setup | Information Intelligence | Business Analytics Server | Configuration | Configuring Search Queries | User Query Language (UQL).

sort_order No array of sort Objects

The defined order is used for multilevel sorting. Maximum limit is 3, to avoid performance issues.

Subattributes:

  • key (string) - Predicate value used for sorting search results. The key attribute can be:

    • The standard ds6w or custom predicate, when the attribute is mapped to a vocabulary predicate.
    • The full MQL attribute name prepended by ds6wg:, when the attribute is not mapped to a vocabulary predicate.

      Replace the following special characters as specified:

      • _ (underscore) by _95_
      • . (period) by _46_
      • " " (quotes) by _
      • : (colon) by "_58_"
      For example, to rewrite ds6w:label as ds6w_58_label

  • value (string) - Default ordering direction. Choose between:

    • asc for ascending
    • and desc for descending

Examples:

//sort_order mapped to standard ds6w with value set to "asc"
{ "ds6w:country": "asc" }, 
//full MQL attribute prepended by ds6wg: with value set to "desc"
{ "ds6wg:xd7_VPMReferenceSP.Supplier": "desc" }

Example 1: PQsDefinitions_Custom.txt

{
  "nbPQ": 4,
  "PQ": [
    {
      "abbreviations": "custoprd6w,custoprdrelease6w,cprdrel6w",
      "id": 1,
      "pqid": "CUSTO_PrdReleased6w",
      "value": "flattenedtaxonomies:\"types/xd7_vpmreferencesp\" AND (label:(__QUERY__) OR identifier:(__QUERY__))",
      "sort_order": [
        {
          "ds6w:label": "asc"
        },
        {
          "ds6w:modified": "desc"
        }
      ]
    },
    {
      "abbreviations": "custodoc6w,cdoc6w",
      "id": 2,
      "pqid": "CUSTO_Doc6w",
      "value": "flattenedtaxonomies:\"types/xd7_documentsp\" AND (label:(__QUERY__) OR identifier:(__QUERY__))"
    },
    {
      "abbreviations": "custoprd,custoprdrelease,cprdrel",
      "id": 3,
      "pqid": "CUSTO_PrdReleased",
      "value": "flattenedtaxonomies:\"types/xd7_vpmreferencesp\" AND (label:(__QUERY__) OR identifier:(__QUERY__) 
      OR ds6wg_58_xd7_95_vpmreferencesp_46_supplier:(__QUERY__) OR ds6wg_58_xd7_95_vpmreferencesp_46_reviewer:(__QUERY__))",
      "sort_order": [
        {
          "ds6wg:xd7_vpmreferencesp.supplier": "asc"
        },
        {
          "ds6wg:xd7_vpmreferencesp.reviewer": "desc"
        }
      ]
    },
    {
      "abbreviations": "custodoc,cdoc",
      "id": 4,
      "pqid": "CUSTO_Doc",
      "value": "flattenedtaxonomies:\"types/xd7_documentsp\" AND (label:(__QUERY__) OR identifier:(__QUERY__) ds6wg_58_supplier1:(__QUERY__) 
      OR ds6wg_58_reviewer1:(__QUERY__))",
      "sort_order": [
        {
          "ds6wg:supplier1": "desc"
        },
        {
          "ds6wg:reviewer1": "asc"
        }
      ]
    }
  ]
}

Example 2: PQsDefinitionsNLS_Custom_en.txt

{
"CUSTO_PrdReleased6w.Title":"Custom Product 6W",
"CUSTO_Doc6w.Title":"Custom Document 6W",
"CUSTO_PrdReleased.Title":"Custom Product",
"CUSTO_Doc.Title":"Custom Document"
}