Integrating in Application

This section is intended for application developers to integrate Trusted Answer Search into their application and build a natural-language interface. The integration can be done in the following ways:

1. Portal APEX App
   A pre-built, end-user facing application that performs search on the Trusted Search system. Enterprise developers can deploy this app to provide search or chatbot functionality for their end-users.

2. PL/SQL Search API
   If enterprise developers do not wish to use the pre-build APEX Portal App, they can directly call the PL/SQL DBMS_TRUSTED_SEARCH.SEARCH() PL/SQL procedure or invoke it through an ORDS REST endpoint.

APEX Portal Experience

Deploy the Trusted Answer Search portal application when you want to provide a stand-alone search experience for end-users without building a custom UI from scratch.

1. Administrator setup
   Your Trusted Answer Search administrator must install the portal app that ships in the installation archive. The setup script provisions the APEX application and makes the portal available at a dedicated URL.

2. Authorize end-users
   Search Space Experts (or Search Administrators) must grant each end-user access to the appropriate search space inside the admin app. Only authorized users can sign in to the portal.

3. Share or link to the portal
   Application developers can either:

   • Add a link or button in their website that redirects users to the hosted portal URL, or
   • Communicate the direct portal link (for example via email or in-product messaging) so users can access it on demand.

What end-users see

• Portal app sign-in

  

• Search results in the brokerage space

  

API Experience

If you need to run searches from your own backend service, call the Trusted Answer Search PL/SQL procedure. The application developer is responsible for authenticating and authorizing end-users in their application and ensuring they are permitted to query the target search space.

Connect to the Trusted Answer Search database using your preferred driver (JDBC, python-oracledb, Oracle Call Interface, etc.) and execute the packaged procedure in the DBMS_TRUSTED_SEARCH PL/SQL package:

PROCEDURE search (
    p_user_query              IN  VARCHAR2,
    p_search_space            IN  VARCHAR2,
    p_search_space_version_id IN  VARCHAR2 DEFAULT NULL,
    p_search_record           OUT JSON
);

Arguments:

• p_user_query – Natural-language query supplied by the end-user.
• p_search_space – Name of the search space (e.g., brokerage).
• p_search_space_version_id – Optional version ID of the search space. It is recommended to omit this argument so that the default version (i.e., the published version) is queried. However, you can get this ID from the Search Space Versions page in the Admin app to pass another version ID.
• p_search_record – JSON document returned by the procedure containing search hits and relevant metadata.

Exceptions / errors:

• -20006 – Raised when p_search_space cannot be resolved (unknown search space name).
• -20005 – Raised when p_user_query exceeds 2,000 characters.
• -20004 – Raised when validation fails (query is NULL/blank/vector-like, no published version exists when p_search_space_version_id is NULL, or the supplied version ID is invalid/mismatched).
• -20003 – Raised when the caller does not have access to the specified search space.

Example (brokerage search space):

DECLARE
  l_result JSON;
BEGIN
  dbms_trusted_search.search(
    p_user_query    => 's&p500 index level',
    p_search_space  => 'brokerage',
    p_search_record => l_result
  );

  DBMS_OUTPUT.put_line(l_result.to_string);
END;
/

Sample p_search_record JSON for the query “s&p500 index level”:

{
  "version": 1,
  "id": "b0f4fd97-8f6f-47a7-9ac1-55b1a2c9d5fd",
  "user_query": "s&p500 index level",
  "search_matches": [
    {
      "rank": 1,
      "search_target_id": "7a3f8fb3-6b2d-4cf2-95bb-3c8d329cb6a4",
      "search_target_title": "Stock Index Performance",
      "match_candidate_type": "SAMPLE_QUERY",
      "original_candidate": "quote for S&P500 index level",
      ...
      "score": 0.9142,
      "url": "https://brokerage123.com/markets/index?symbol=GSPC",
      "target_input_matches": {
        "INDEX_SYMBOL": "GSPC"
      }
    },
    {
      "rank": 2,
      "search_target_id": "2f4d59b9-7de2-4f63-931c-2aaf61b86f3e",
      "search_target_title": "Stocks, ETFs, and Index Research",
      "match_candidate_type": "TARGET_DESCRIPTION",
      "original_candidate": "This report shows research on stocks,ETFs, and stock indexes.",
      ...
      "score": 0.7575,
      "url": "https://brokerage123.com/research/investing-in-stocks-etfs-indexes",
      "target_input_matches": {}
    }
  ]
}

Use the returned JSON to render answers, links, or actions from your application.