adding search doc column to at_physical_location (#123)

* adding search doc column to at_physical_location

this will allow an Oracle Text index to be used and then allow fast search using CONTAINS within CDA queries for text search

Author: adamkorynta

docker-compose.yml

@@ -10,9 +10,16 @@ services:
       - ORACLE_PASSWORD=password
     ports:
       - "1521:1521"
+    healthcheck:
+      test: [ "CMD-SHELL", "echo 'SELECT 1 FROM dual;' | sqlplus -s sys/${ORACLE_PASSWORD}@localhost/FREEPDB1 as sysdba | grep -q '1'" ]
+      interval: 10s
+      timeout: 5s
+      retries: 30
+      start_period: 60s
+
   schema:
     build:
-      context: ./schema
+      context: .
     container_name: cwms-dev-schema
     environment:
       - DB_HOST_PORT=cwms-dev-db:1521
@@ -25,6 +32,6 @@ services:
       - OFFICE_EROC=S0
       # With installonce set to 0 the schema will be removed (equivalent to ant clean build) each time this runs.
       - INSTALLONCE=0
-      - QUIET=0  
+      - QUIET=0
 volumes:
   cwms-dev-oracle:

schema/src/buildCWMS_DB.sql

@@ -401,10 +401,11 @@ begin
    dbms_utility.compile_schema('&cwms_schema');
 end;
 /
+
 prompt Rebuilding all disabled function-based indexes...
 begin
    for rec in (select index_name from all_indexes where owner = '&cwms_schema' and funcidx_status = 'DISABLED') loop
-      execute immediate 'alter index &cwms_schema..'||rec.index_name||' rebuild';
+         execute immediate 'alter index &cwms_schema..'||rec.index_name||' rebuild';
    end loop;
 end;
 /
@@ -421,6 +422,8 @@ exception
 end;
 /
 
+
+@@cwms/oracle_text/setup_indexes.sql
 --
 -- all done
 --

schema/src/cwms/at_schema.sql

@@ -240,6 +240,7 @@ CREATE TABLE AT_PHYSICAL_LOCATION
   OFFICE_CODE         NUMBER(14),
   NATION_CODE         VARCHAR2(2),
   NEAREST_CITY        VARCHAR2(50),
+  SEARCH_DOC          VARCHAR2(1000),
   CONSTRAINT AT_PHYSICAL_LOCATION_PK  PRIMARY KEY (LOCATION_CODE) USING INDEX
 )
 TABLESPACE CWMS_20AT_DATA
@@ -283,6 +284,7 @@ COMMENT ON COLUMN AT_PHYSICAL_LOCATION.PUBLISHED_LONGITUDE IS 'Longitude of loca
 COMMENT ON COLUMN AT_PHYSICAL_LOCATION.OFFICE_CODE         IS 'References the office who''s bounday contains this location.';
 COMMENT ON COLUMN AT_PHYSICAL_LOCATION.NATION_CODE         IS 'References the nation containing this location.';
 COMMENT ON COLUMN AT_PHYSICAL_LOCATION.NEAREST_CITY        IS 'Name of city nearest this location.';
+COMMENT ON COLUMN AT_PHYSICAL_LOCATION.SEARCH_DOC          IS 'Placeholder column for Oracle Text full-text search index. The indexed document text is dynamically generated by the USER_DATASTORE procedure (CWMS_LOC.BUILD_SEARCH_DOC) during indexing and is not stored in this column.';
 
 
 ALTER TABLE AT_PHYSICAL_LOCATION ADD CONSTRAINT AT_PHYSICAL_LOCATION_CK1 CHECK (TRIM(SUB_LOCATION_ID) = SUB_LOCATION_ID);
@@ -311,11 +313,11 @@ STORAGE    (
            )
 NOPARALLEL
 /
-
+SHOW ERRORS;
 
 INSERT INTO at_physical_location
-            (location_code, base_location_code, active_flag, location_kind)
-     VALUES (0, 0, 'F', 1);
+(location_code, base_location_code, active_flag, location_kind)
+VALUES (0, 0, 'F', 1);
 
 COMMIT;
 

schema/src/cwms/cwms_loc_pkg.sql

@@ -3167,6 +3167,62 @@ AS
       p_datums      in  varchar2 default null,
       p_office_id   in  varchar2 default null)
       return clob;
+
+
+   /**
+    * Builds the search document for a location specifically for use by Oracle Text.
+    *
+    * <p>This procedure is used by the Oracle Text <code>USER_DATASTORE</code> defined
+    * for the <code>AT_PHYSICAL_LOCATION.SEARCH_DOC</code> column. During text index
+    * creation or synchronization, the procedure constructs a denormalized text document
+    * containing ids and metadata which are tokenized and stored in the text index.</p>
+    *
+    * <p>The resulting text is not stored in the <code>SEARCH_DOC</code> column itself.
+    * It is used by the Oracle Text indexing engine and stored in the text index tables associated with the
+    * <code>AT_PHYSICAL_LOCATION_SEARCH_IDX</code> index.</p>
+    *
+    * <p>The generated document may include values such as:</p>
+    * <ul>
+    *   <li>Base location id</li>
+    *   <li>Sub-location id</li>
+    *   <li>Combined location identifier (<code>BASE-SUB</code>)</li>
+    *   <li>Public name</li>
+    *   <li>Long name</li>
+    *   <li>Description</li>
+    *   <li>Map label</li>
+    *   <li>Nearest city</li>
+    *   <li>Location kind id</li>
+    *   <li>Location type</li>
+    * </ul>
+    *
+    * <p>This enables full-text search queries such as:</p>
+    *
+    * <pre>
+    * SELECT  SCORE(1) AS relevance,
+    *   location_id,
+    *   public_name,
+    *   long_name,
+    *   nearest_city
+    *  FROM av_loc
+    *  WHERE CONTAINS(search_doc, '(FOLSOM AND DAM) OR (AMERICAN AND RIVER)', 1) > 0
+    *  ORDER BY SCORE(1) DESC;
+    * </pre>
+    *
+    * <p>The procedure is executed automatically during:</p>
+    * <ul>
+    *   <li>Initial creation of the Oracle Text index</li>
+    *   <li>Index synchronization operations</li>
+    *   <li>Row updates when the index is configured with <code>SYNC (ON COMMIT)</code></li>
+    * </ul>
+    *
+    * @param p_rowid The <code>ROWID</code> of the <code>AT_PHYSICAL_LOCATION</code> row
+    *
+    * @param p_doc The generated search document text returned to the Oracle Text engine for tokenization and indexing.
+    */
+   procedure build_search_doc(
+      p_rowid in rowid,
+      p_doc   out varchar2
+   );
 END cwms_loc;
 /
 

schema/src/cwms/cwms_loc_pkg_body.sql

@@ -2483,6 +2483,10 @@ AS
             UPDATE   at_base_location abl
                SET   base_location_id = l_base_location_id_new
              WHERE   abl.base_location_code = l_base_location_code_old;
+            -- innocuous update that will force a reindex on at_physical_location.search_doc
+            UPDATE at_physical_location
+               SET search_doc = search_doc
+               WHERE base_location_code = l_base_location_code_old;
          --
          WHEN l_sub_location_id_new IS NULL
          THEN                             -- Old Loc renamed to new Base Loc --
@@ -11052,6 +11056,40 @@ end unassign_loc_groups;
       v_package_log_prop_text := nvl(p_text, sys_context('userenv', 'sid'));
    end set_package_log_property_text;
 
+   procedure build_search_doc(
+      p_rowid in rowid,
+      p_doc   out varchar2
+   )
+      is
+   begin
+      select max(
+                coalesce(b.base_location_id,'') || ' '
+                   || coalesce(pl.sub_location_id,'') || ' '
+                   || case
+                         when pl.sub_location_id is not null
+                            then b.base_location_id || '-' || pl.sub_location_id || ' '
+                         else ''
+                   end
+                   || coalesce(pl.public_name,'') || ' '
+                   || coalesce(pl.long_name,'') || ' '
+                   || coalesce(pl.description,'') || ' '
+                   || coalesce(pl.map_label,'') || ' '
+                   || coalesce(pl.nearest_city,'') || ' '
+                   || coalesce(k.location_kind_id,'') || ' '
+                   || coalesce(pl.location_type,'')
+             )
+      into p_doc
+      from at_physical_location pl
+              left join at_base_location b
+                        on b.base_location_code = pl.base_location_code
+              left join cwms_location_kind k
+                        on k.location_kind_code = pl.location_kind
+      where pl.rowid = p_rowid;
+
+      p_doc := coalesce(p_doc, '');
+
+   end build_search_doc;
+
 begin
    g_location_code_cache.name := 'cwms_loc.g_location_code_cache';
    g_location_id_cache.name   := 'cwms_loc.g_location_id_cache';

schema/src/cwms/oracle_text/setup_indexes.sql

@@ -0,0 +1,44 @@
+/*
+ * Copyright (c) 2026
+ * United States Army Corps of Engineers - Hydrologic Engineering Center (USACE/HEC)
+ * All Rights Reserved.  USACE PROPRIETARY/CONFIDENTIAL.
+ * Source may not be released without written approval from HEC
+ */
+prompt Creating Oracle Text preferences and indexes
+
+begin
+   ctx_ddl.drop_preference('loc_search_ds');
+exception when others then null;
+end;
+/
+begin
+   ctx_ddl.create_preference('loc_search_ds', 'USER_DATASTORE');
+   ctx_ddl.set_attribute('loc_search_ds', 'PROCEDURE', '&cwms_schema..cwms_loc.build_search_doc');
+   ctx_ddl.create_preference('loc_search_lexer', 'BASIC_LEXER');
+   ctx_ddl.create_preference('loc_search_wordlist', 'BASIC_WORDLIST');
+end;
+/
+commit;
+
+begin
+   execute immediate 'drop index at_physical_location_search_idx';
+exception
+   when others then
+      if sqlcode != -1418 then raise; end if;
+end;
+/
+create index at_physical_location_search_idx
+   on at_physical_location (search_doc)
+   indextype is ctxsys.context
+   parameters ('datastore loc_search_ds
+       lexer loc_search_lexer
+       wordlist loc_search_wordlist
+       sync (on commit)');
+/
+
+alter index CWMS_20.AT_PHYSICAL_LOCATION_SEARCH_IDX rebuild;
+
+begin
+   ctx_ddl.sync_index('AT_PHYSICAL_LOCATION_SEARCH_IDX');
+end;
+/

schema/src/cwms/views/av_loc.sql

@@ -56,6 +56,7 @@ insert into at_clob
  * @field nation_id            Nation encompassing location (may be inherited from base location)
  * @field nearest_city         City nearest to location (may be inherited from base location)
  * @field active_flag          Depricated - loc_active_flag replaces active_flag as of v2.1
+ * @field search_doc           Placeholder column for Oracle Text full-text search index. The indexed document text is dynamically generated by the USER_DATASTORE procedure (CWMS_LOC.BUILD_SEARCH_DOC) during indexing and is not stored in this column.
  */
 ');
 
@@ -90,7 +91,8 @@ select LOCATION_CODE,
        BOUNDING_OFFICE_ID, 
        NATION_ID, 
        NEAREST_CITY, 
-       active_flag
+       active_flag,
+       SEARCH_DOC
 from 
 ( with phy_loc as
   ( select loc.location_code,
@@ -119,7 +121,8 @@ from
            nvl (loc.nearest_city, bas.nearest_city)   as nearest_city,
            blo.active_flag                            as base_loc_active_flag,
            loc.active_flag                            as loc_active_flag,
-           loc.active_flag                            as active_flag
+           loc.active_flag                            as active_flag,
+           loc.search_doc
     from  -- join the base location metadata (bas) with the location (loc)
           cwms_20.at_physical_location loc left join
           cwms_20.at_physical_location bas on ( bas.location_code = loc.base_location_code ) left join

schema/src/cwms/views/av_loc2.sql

@@ -64,6 +64,7 @@ insert into at_clob
  * @field loc_alias_category   The location category that owns the location group to which the alias for the location_id or base_location_id belongs. Null if location_id is not an alias.
  * @field loc_alias_group      The location group to which the alias for the location_id or base_location_id belongs. Null if location_id is not an alias.
  * @field db_office_code       Unique number identifying the office that owns the location
+ * @field search_doc           Placeholder column for Oracle Text full-text search index. The indexed document text is dynamically generated by the USER_DATASTORE procedure (CWMS_LOC.BUILD_SEARCH_DOC) during indexing and is not stored in this column.
  */
 ');
 
@@ -102,7 +103,8 @@ create or replace force view av_loc2
    aliased_item,
    loc_alias_category,
    loc_alias_group,
-   db_office_code
+   db_office_code,
+   search_doc
 )
 as
    select q1.location_code,
@@ -141,7 +143,8 @@ as
           q1.aliased_item,
           q1.loc_alias_category,
           q1.loc_alias_group,
-          q1.db_office_code
+          q1.db_office_code,
+          pl.search_doc
      from (------------------------------------
            -- location and alias ids, office --
            ------------------------------------
@@ -227,6 +230,8 @@ as
                and lc.loc_category_code = lg.loc_category_code
            )
           ) q1
+          join at_physical_location pl
+               on pl.location_code = q1.location_code
           join
           (--------------------------------------
            -- unit system, unit, and elevation --