Searcher Service
Overview
The objective of egov-searcher service is listed below.
To provide a one-stop framework for searching data from multiple data-source based on configuration (Postgres, Elasticsearch etc).
To create provisions for implementing features based on ad-hoc requirements which directly or indirectly require a search functionality.
Pre-requisites
Prior knowledge of Java/J2EE
Prior knowledge of SpringBoot
Prior knowledge of PostgresSQL
Prior knowledge of REST APIs and related concepts like path parameters, headers, JSON etc.
Prior knowledge of JSONQuery in Postgres. (Similar to PostgresSQL with a few aggregate functions.)
Setup & Key Functionalities
Setup
Step 1: Write the configuration as per your requirement. The structure of the config file is explained later in the same doc.
Step 2: Check-in the config file to a remote location preferably GitHub, currently we check the files into this folder - https://github.com/egovernments/configs/tree/DEV/egov-searcher for DEV and QA and this folder - https://github.com/egovernments/configs/tree/UAT/egov-searcher for UAT.
Step 3: Provide the absolute path of the checked-in file to DevOps, to add it to the file-read path of egov-searcher. The file will be added to egov-searcher's environment manifest file for it to be read at the start-up of the application.
Step 4: Run the egov-searcher app, and use the modulename and definitionname parameters from the configuration as path parameters in the URL of the search API to fetch the required data.
Definitions
Config file - A YAML (xyz.yml) file which contains configuration for search requirements.
API - A REST endpoint to fetch data based on the configuration.
Functionality
Uses Postgres JSONQuery instead of SQL queries to fetch data from the Postgres DB.
JSONQuery: JSONQuery is one of the exclusive features of Postgres, It provides a way of fetching data from the DB as JSON instead of ResultSet format. This saves the time spent mapping ResultSet into required JSON formats on the functionality side. JSONQueries are similar to SQL queries with certain functions to internally map the ResultSet to JSON. SQL queries (SELECT queries to be precise) are passed as parameters to these functions, the SQL Query returns the ResultSet which is transformed into the JSON by these functions.
Some of the functions extensively used are: 1) row_to_json: This function takes a query as a parameter and converts the result into JSON. However, the query must return only one row in the response. Note that, JSONQuery functions operate on aliases, So, the query must be mapped to an alias and the alias is passed to the function as a parameter. For example: {"name": "egov", "age": "20"} 2) array_agg: This functions takes the output of row_to_json and aggregates it into an array of JSON. This is required when the query is returning multiple rows in the response. The query will be passed to row_to_json through an alias, this is further wrapped within array_agg to ensure all the rows returned by the query as converted to a JSONArray. For example: [{"name": "egov", "age": "20"},{"name": "egov", "age": "20"},{"name": "egov", "age": "20"}] 3) array_to_json: This transforms the result of array_agg into a single JSON and returns it. This way, the response of a JSONQuery will always be a single JSON with the JSONArray of results attached to a key. This function is more for the final transformation of the result. The result so obtained can be easily cast to any other format or operated on using the PGObject instance exposed by Postgres. For example: {"alias": [{"name": "egov", "age": "20"},{"name": "egov", "age": "20"},{"name": "egov", "age": "20"}]}
For more details about JSONQuery, please check: JSON Functions and Operators
Provides an easy way to set up search APIs on the fly by adding configurations without any coding effort.
Provides flexibility to build where clause as per requirement, with config keys for operators, conditional blocks and other query clauses.
Designed to use a specific URI for every search request, making role-based access control easy.
Fetches data in the form of JSON the format of which can be configured. This saves considerable effort in writing row mappers for every search result.
Interaction Diagram
Deployment Details
Add configs for different modules required for Searcher Service.
Deploy the latest version of Searcher Service.
Add role-action mapping for APIs.
Integration Details
Integration Scope
The searcher service is used to search for data present in databases by running PSQL queries in the background.
Integration Benefits
Can perform service-specific business logic without impacting the other module.
In the future, if we want to expose the application to citizens then it can be done easily.
Integration Steps
To integrate, the host of the searcher-service module should be overwritten in the helm chart.
searcher/{moduleName}/{searchName}/_getshould be added as the search endpoint for the config added.
API Details
URI: The format of the search API to be used to fetch data using egov-searcher is as follows: /egov-searcher/{moduleName}/{searchName}/_get
Every search call is identified by a combination of moduleName and searchName. Here, 'moduleName' is the name of the module as mentioned in the configuration file and 'searchName' is the name of the definition within the same module that needs to be used for our search requirement.
For instance, If I want to search all complaints on PGR I will use the URI - /egov-searcher/rainmaker-pgr-V2/serviceSearchWithDetails/_get
Body: The body consists of 2 parts: RequestInfo and searchCriteria. searchCriteria is where the search params are provided as key-value pairs. The keys given here are the ones to be mentioned in the 'jsonPath' configuration within the 'searchParams' key of the config file.
For instance, If I want to search complaints on PGR where serviceRequestId is 'ABC1234' and tenantId is 'pb.amritsar' the API body will be:
Last updated
