Getting Started

Use these tasks to install Oracle Trusted Answer Search, configure search spaces and targets, manage versions and user access, and validate search results in the portal application.

Admin Setup

Installation

Download the Trusted Answer Search installation archive from https://oracle.com/downloads. After downloading, open the archive and follow README.md to deploy all components, including the back-end services and the APEX administrative and portal applications.

If you plan to use LLM-backed target input extraction or LLM-assisted result re-ranking, install the LLM components after the base deployment. First, run the back-end installer with LLM_INSTALLATION=TRUE to enable and compile the database-side LLM feature path, verify DBMS_CLOUD and DBMS_CLOUD_AI, and seed TRUSTED_SEARCH_USE_LLM=true. Then run the separate LLM provider setup script, setup_oci_connection.sh, with setup_oci_connection.conf.

The LLM provider setup creates the runtime cloud credential, the Cloud AI profile, and the default Trusted Search LLM profile configuration. This setup supports both OCI Generative AI and OpenAI-compatible endpoints. For on-premises deployments, the setup script also performs wallet, certificate, proxy, and network ACL configuration. For ADB-S deployments, those host-side steps are skipped and only the database-side provider configuration and validation steps are performed. By default, the setup concludes by running an LLM smoke test to validate the configured profile.

Authentication Configuration During Installation

During installation, select the authentication method that your deployment will use. The value you provide for INITIAL_SEARCH_ADMINISTRATOR_USERNAME must match the selected authentication method.

Social Sign-In

For Social Sign-In, specify the username configured in your SSO provider as INITIAL_SEARCH_ADMINISTRATOR_USERNAME, for example, [e-mail]. After installation, configure the APEX application’s authentication scheme to use Social Sign-In.

Database Accounts

For Database Accounts, specify the database username that you want to assign as INITIAL_SEARCH_ADMINISTRATOR_USERNAME. After installation, configure the APEX application to use Database Accounts as its authentication scheme.

Quick Start

When installation completes, open the apex_ship/QUICK_START.md guide inside the archive. Use the walkthrough to import the sample Wikimedia Stats or Trusted SQL search space and run search queries from the portal app to validate the deployment.

Creating Search Spaces

If you skipped the sample import in the Quick Start guide or if the wikimedia search space was not created automatically, you can add it manually in the admin app using the following steps.

1. Sign in with your Search Administrator or Search Space Expert credentials. You may use the privileged tasadmin account.

1. Select Search Spaces in the left navigation. The table lists every search space that currently exists.

   

2. Select Create Search Space (or edit an existing entry) to open the configuration drawer. Provide a concise internal Name such as WIKIMEDIA, then focus on the fields that power the end-user portal experience:

   • Search Space Title shown in the Portal App – the heading displayed in the results rail.

   • Description shown in the Portal App – a short paragraph that tells users what queries this space answers.

   • Search Bar Placeholder Text in the Portal App – the hint text that appears inside the search box.

   These strings are customer-facing, so write clear, contextual guidance that matches the intent of your audience.

   

3. Select Create. The new search space appears in the table and can now hold search targets. You can now create search targets.

Configuring Search Space Visibility

Search spaces support Public and Private visibility settings.

• Public: Any authenticated user can search the search space. Only Search Space administrators can modify its configuration.

• Private: Only users who have been explicitly granted access can search the search space. Administrative privileges remain limited to Search Space administrators.

Configuring LLM Re-ranking for a Search Space

If LLM support is installed, a Search Administrator can enable LLM-assisted re-ranking for each search space. LLM re-ranking runs after hybrid retrieval and reorders the candidate targets returned by the lexical and semantic retrieval steps.

Use the following fields when configuring the search space:

• Use LLM?: Select Yes to enable LLM features for the search space.

• Select LLM Profile: Select the LLM profile to use for search-space LLM operations.

• Rerank Results With LLM?: Select Yes to apply LLM-assisted re-ranking after hybrid retrieval.

• ReRanking Candidate Pool Size: Specify how many candidate targets returned by hybrid retrieval are passed to the LLM re-ranking step. A smaller pool limits the number of candidates evaluated by the LLM, while a larger pool gives the LLM more candidates to reorder.

• Custom LLM Instructions: Optionally provide instructions that guide how the LLM should prioritize candidate targets. For example, you can instruct the LLM to prefer broad targets for broad queries and more specific targets for specific queries.

Building Search Targets

Use the admin app to curate search targets that surface reliable answers for every user query. The following steps illustrate how to create a “Total Page Views - All Projects” search target inside the wikimedia search space.

1. Sign in to the admin console with Search Administrator credentials. After authentication, you land on the dashboard. Note the global Search Space selector in the header at top-right.

   

2. Open the Search Space dropdown and select wikimedia, then select Search Targets in the left navigation to load the catalog for that space.

   

3. Select Create Target on the top-right of the page. The form opens with three steps. Provide the general metadata first.
   • Search Target Title – Total Page Views - All Projects

   • Search Target Description – The target description should semantically describe what this target is about. This description is used during Trusted Answer Search retrieval and directly impacts search quality.

     Enter this description: This report shows overall pageview volume across all Wikimedia projects over time. It opens a time-series chart with a table view and supports changing the time window and daily or monthly granularity. It is useful for readers, analysts, and community members tracking overall demand for Wikimedia content.

   

4. In Step 2: Select Target Action, select URL and paste https://stats.wikimedia.org/#/all-projects/reading/total-page-views/normal|bar|:period|~total|:frequency into the URL field. The form validates the link automatically. The app detects the :period and :frequency placeholders and displays them as target inputs. Map :period to the PERIOD Target Value Set and :frequency to the FREQUENCY Target Value Set.

5. In Step 3: Add Sample Queries, supply realistic prompts that should retrieve this target. Each sample query must mirror the language your app’s end-users naturally use; specific scenarios and intent-driven phrasing guide semantic matching.

   Enter the following queries into the Sample Query box and select Add Sample Query after every entry. For example:

   • What is the daily pageview trend for all Wikimedia projects?
   • Show monthly page views for all Wikimedia projects.

   As you add them, the table beneath the input lists the saved queries.

   

6. Select Create Search Target. The button is enabled after you provide the title, description, target action, target input mappings, and sample queries. The new “Total Page Views - All Projects” target appears in the wikimedia catalog.

   The search target does not appear in end-user search results until you publish the draft search space version. Publish the search space version after you finish making and reviewing the draft changes.

   Search Space versioning is explained later in this document.

Configuring Target Inputs

Some reports require parameters before they can resolve to the required view. For example, the Wikimedia page-view target can use a time period and a frequency value to control the chart. Instead of creating separate search targets for each combination, use Target Inputs so Trusted Answer Search can substitute values from the user’s query into the action URL or SQL.

The “Total Page Views - All Projects” target uses the following URL template:

https://stats.wikimedia.org/#/all-projects/reading/total-page-views/normal|bar|:period|~total|:frequency

In this URL, :period and :frequency are target input placeholders. Each placeholder must be mapped to a Target Value Set so Trusted Answer Search can resolve values from natural-language queries.

1. From Search Targets, select Create Target to create the “Total Page Views - All Projects” search target.

   • Title: Total Page Views - All Projects
   • Description: This report shows overall pageview volume across all Wikimedia projects over time. It opens a time-series chart with a table view and supports changing the time window and daily or monthly granularity.

   

2. Under Step 2: Select Target Action, select URL and paste the parameterized link. The app automatically detects :frequency and :period and exposes both rows in the Target Inputs table beneath the URL.

   

3. Select Create New Target Set to launch the Add Target Value Set dialog.

   For this example, create a manual Target Value Set for FREQUENCY.

   • Name: FREQUENCY
   • Description: Time bucket options that control the resolution of the trends

   Select Manual as the source. Add values such as monthly, with synonyms such as by month, month, and monthly view, then set the default value to monthly. Create the PERIOD Target Value Set the same way, using the valid time-window values and synonyms for the Wikimedia report.

   

4. Save the value sets and select them from the Target Value Set dropdowns so frequency maps to FREQUENCY and period maps to PERIOD. The table now shows which value set will supply runtime substitutions for each target input.

   

With the mapping in place, a search query such as “Show monthly page views for all Wikimedia projects” can resolve :frequency to monthly and substitute that value into the target URL. Use the same pattern for table-driven value sets when a data team owns authoritative lists: point the target input at the refreshed table column instead of entering static rows.

Creating Table-Column Target Value Sets

Use a table-column Target Value Set when the valid values for a target input already exist in an application table or view. The target input mapping remains the same as a manual set, but values are collected from a source table or source view column instead of being entered one by one.

1. Open Target Value Sets from the left navigation.

2. Select a draft search space version. Target Value Sets can be created or changed only while the version is in draft state.

3. Select Create Target Value Set.

4. Enter the shared fields:

   • Name: Target Value Set name shown in the Target Input mapping dropdown.

   • Description: Short description of what the values represent.

   • Source: Select Column-Based.

5. Complete the table-column source fields:

   • Schema Name: Owner of the source table or view.

   • Is it a Remote Table?: Select No for a local table, or Yes when values must be read through a database link. The database link must already exist before it can be used. Use either a public database link or a database link created in the TASADMIN schema.

   • Database Link: Database link name. This field is used only for remote table or view sources.

   • Table Name: Source table or view containing the candidate values.

   • Column Name: Source column whose distinct non-null values become Target Value Set values.

   • Synonym columns: Optional columns from the same source table or view. Non-null values in these columns become synonyms for the value from the selected value column.

   • Default Value: Fallback value used when a query does not mention a value that can be resolved.

   

6. Select Save. The new set appears in the Target Value Sets catalog and can be selected in the same Target Value Set dropdown used by manual sets.

At search time, usage is the same as a manual set. Map a target input placeholder such as :frequency or :period to the table-column Target Value Set. Trusted Answer Search resolves the user’s words to one of the collected values, then substitutes that value into the target URL or SQL action.

Table-column sets can also be synchronized. Use sync when the source table or view has changed and the Target Value Set should be refreshed from the current source contents. Sync rereads the configured schema, source object, column, database link, and synonym columns; adds new source values; removes values no longer present; and updates derived synonyms. If values or synonyms changed, Trusted Answer Search refreshes the supporting vocabulary and recomputes dependent embeddings.

Creating LLM-Backed Target Value Sets

Use an LLM-backed Target Value Set when the target input is not a fixed enumeration. Instead of matching against stored values, Trusted Answer Search asks the configured LLM model to extract the value from the user’s query according to the instruction you provide. Common examples include dates, people, numbers, currencies, percentages, and custom values that users may phrase in many forms.

1. Open Target Value Sets and select Create Target Value Set on a draft search space version.

2. Enter Name and Description.

3. For Source, select LLM-Based.

4. Complete the LLM fields:

   • LLM Presets: Select a preset such as DATE, PERSON, NUMBER, CURRENCY, or PERCENTAGE, or select Custom. Presets populate the instruction and output format with seeded responses.

   • Default Value: Fallback value used when extraction fails or the query does not provide a usable value.

   • LLM Instruction: Instruction that tells the LLM what to extract from the query. This field is required for LLM-backed sets.

   • LLM Output Format: Optional formatting guidance for the extracted value, such as returning only a number or returning a date in a specific format.

   

5. Select Save and map the Target Value Set to a target input just as you would with a manual set.

LLM-backed sets do not store a list of values or synonyms. During search, Trusted Answer Search sends the user query and the LLM-backed Target Value Set instructions to the configured LLM profile, parses the extracted value, and uses it as the target input value. Table-column source fields and manual values are not used for LLM-backed sets.

After configuring the target inputs required by your search targets, publish the draft search space version so end-users can reach the updated catalog.

Managing Search Space Versions

The following section allows a Search Administrator or Search Space Expert to review and promote changes to a search space.

1. From Search Spaces, locate the search space you are working on, in this example, WIKIMEDIA. The row shows the search space visibility, number of versions, published version, associated search target count, and portal display text. Use this page to confirm that you are working with the intended search space before reviewing version changes.

   

2. Select WIKIMEDIA to open the versions dashboard. The version list and version tree show the currently published version, the active draft version, and any unpublished versions. Verify that the draft version is present before generating diffs or publishing changes.

   

3. Select See Diffs to open the Diff Generator. Select the currently published version as the base version and the draft version as the new version, then select Generate. The Diff Generator groups changes into search target changes, target value set changes, and feedback changes.

   In this example, the search target changes include an added sample query for Unique Devices Trend and a removed sample query for User Edits (Human Editor) Trend. The target value set changes show updates to the PERIOD value set, including modified LLM instructions and modified LLM output format. Removed content is shown in red and added content is shown in green.

   

   You can collapse individual diff sections after reviewing the details. In this example, no feedback diffs were generated.

   

4. Return to the Search Space versions view. Use the action menu (three dots) next to the draft version and select Regressions to inspect whether previously answered queries would map to different search targets after publishing. There should not be any regressions in this example.

   

5. Return to the Search Space versions view, open the action menu (three dots) next to the draft version again, and select Publish to promote the draft. Publishing makes the search space version available to end-users.

   

With the draft changes published, add an end-user who can query the wikimedia search space.

Managing User Access

Trusted Answer Search user access depends on the authentication method selected during installation. For Database Accounts deployments, each user must exist as a database account before you authorize that user to access the Trusted Answer Search application. For Social Sign-In deployments, users authenticate through your SSO provider, and you grant the appropriate Trusted Answer Search roles and search space access in the admin app.

The following steps add a Search Space User called tasuser for a Database Accounts deployment. Run the following statement, or ask your database administrator (DBA), to provision a search-only account:

create user tasuser identified by tasuser;

1. Sign in to the admin app as tasadmin, select Users in the left navigation, and confirm that you are managing access for the Wikimedia search space. The report lists existing administrators, experts, and search-only users.

   

2. Select Add User to open the drawer. Enter tasuser, select only the User role, and select wikimedia from the Search Space list so the new account is scoped to the intended search space. Finish by selecting Add.

   

3. The Users table immediately shows TASUSER. Select the username to review the access drawer. The Search Space Access region confirms that the account has User access to wikimedia; add or revoke other spaces here as needed.

   

After adding the search space user, sign in to the wikimedia search space using that account.

Querying on Portal App

1. Launch the portal application in a fresh session and sign in with tasuser / tasuser.

   

2. After login, pick WIKIMEDIA from the Search Space menu, type italian page views into the question box, and submit the search. The results show Wikimedia page-view targets that match the query. Notice that Trusted Answer Search extracts values from the query and displays target inputs such as language: it, along with configured values such as period: 2-year, project: wikipedia, and frequency: monthly.

   

3. Selecting a result such as Total Page Views opens the curated Wikimedia report in a new browser tab. The link resolves to the Wikimedia statistics URL with the extracted and configured target input values substituted into the URL.

Once the sample query is working end-to-end, explore how a Search Space Expert can improve search results over time.

Human-in-the-loop refinement

Search Space Experts can influence search target retrieval by rewarding accurate matches and suppressing noisy matches.

Feedback from Search Space Experts is recorded against the draft search space version, or against a published version when Settings > Edit Published Versions? is set to Yes. For this example, Edit Published Versions? is set to Yes.

1. In the Admin app, open the italian page views query in Search History or Query Tester. The results show Page Views by Country Map at rank 1 and Total Page Views at rank 2. Select Upvote on the Total Page Views card to promote it. An admin might do this when Total Page Views is the report their end-users expect for a general page-view question, while the country-map result is more specific than the user’s intent. The Admin Upvoted badge confirms that the adjustment is recorded for the current search space version.

   

2. Re-run italian page views in the Portal app. The promoted Total Page Views target now appears at the top of the result list, ahead of Page Views by Country Map and Top Viewed Articles. The search target, target input values, and Wikimedia URL stay curated; only the ranking changes because the Search Space Expert marked Total Page Views as the better answer for this query pattern.

   

3. End-users can also provide feedback from the Portal app by using the thumbs up and thumbs down controls on each result. In this example, a user downvotes Legacy Page Views (Pre-2016) because it is not the best answer for a current italian page views query. That result covers historical traffic before 2016, while the user is asking for ordinary Italian page-view reporting. In the Admin app, the User Downvoted badge shows that Trusted Answer Search captured the user signal for Search Space Expert review.

   

   Portal feedback is advisory at this stage. Trusted Answer Search does not apply the user’s downvote to ranking until a Search Space Expert reviews and confirms it in the Admin app.

4. In the Admin app, open the feedback drawer for the query and confirm the downvote on Legacy Page Views (Pre-2016). An admin might confirm this signal when the target is technically related to page views but consistently distracts from the fresher page-view reports that users want. After confirmation, Legacy Page Views (Pre-2016) shows both User Downvoted and Admin Downvoted badges, indicating that the Search Space Expert has accepted the user’s feedback.

   

5. Re-run italian page views in the Portal app. The admin-confirmed downvoted target drops out of the top results, and a different curated target, such as New Pages Creation Trend, can appear instead. This confirms that the accepted downvote suppresses the noisy match for similar future queries while keeping the result set tied to approved Wikimedia search targets.

   

Human-in-the-loop refinement keeps your published experience aligned with user intent: reward the search targets that answer the question correctly, demote bad or stale matches, and let experts guide the Trusted Answer Search retrieval process.