Oracle Database 12c release 2 or later: the SQL API will be available on this database.
A user with very high privileges (like SYSTEM) is required for installation.
Windows based or Linux based (CentOS, RedHat, Debian or Ubuntu) operating system x86_64 version. Java 8 runtime environment. The installer will be installed on this machine.
The JChem Server contains index data, so confidential data must be secured. Data is cached and most of the calculation is made on the JChem Server, so high amount of memory and high CPU speed with many cores is recommended.
The communication between the database and the JChem Server is via web services. The database calls the endpoints of the JChem Server on a configured port. Communication speed is a major factor at the performance of some queries.
Download package for your operating system (tar.gz for Mac OS) from JChem Search Engines' download page.
sudo service choral stop
/opt/chemaxon/choral/(on linux) or
C:\Program Files\ChemAxon\choral\(on WIndows)
sudo dpkg -i choral_linux_<version_number>.deb
sudo rpm -i choral_linux_<version_number>.rpminstalled Choral application under /opt/chemaxon/choral/
choral_windows-x64_<version_number>.exe as administrator.
tar xvf choral_unix_<version_number>.tar
Open a terminal window (as administrator in Windows) and go to the installation directory, which is
/opt/chemaxon/choral in Linux, your selected installation directory in Windows and the directory where you have unzipped the tar.gz file in Mac OS.
|choral.init.oracleUrl||The url of the database to connect must be set. The format is jdbc:oracle:thin:@<host>:<port:<sid>.|
|choral.init.hostname||By default, the hostname is detected and offered by the installer. If you want to specify another.|
|choral.init.grantingUser||User with System privileges.|
|choral.init.owner||If you want to have more Choral cartridges installed in the same database, different settings are required in each installation for the following properties.|
You can specify other callback user name (the default is choral_owner)
|choral.init.indexerRole||A cartridge indexer role is created during installation. You can specify the indexer role as (the default is choral_indexer)|
|choral.init.searcherRole||A searcher and general cartridge user role is created during installation. You can specify the searcher role as (the default is choral_searcher)|
|choral.init.useJobs||You can specify if Choral cartridge should create and run jobs to improve data modification performance. The default is true, however, if you don't want to/can't give access rights to do so, you can change this setting to false with some performance loss. In case of true a create job privlege is required for the choral_owner.|
Set up allocated memory in choral.conf file
Serves for further configurations, e.g. for tuning the performance of the search processes. Its modification is optional.
The full heap memory given to the server can be set in the choral-service.vmoptions file, while its distribution can be set in the choral.conf file. A memory calculation page is available to generate optimal memory settings. Memory settings can be changed and be applied after restarting the service
After the installation is finished, the CHORAL_SETTINGS table of the callback user (by default CHORAL_OWNER) stores the HOST IP address and PORT number of the installed Choral server. Choral server’s host and port can be configured here.
Create molecule type files
Molecule types define the interpretation mode of the chemical structures. The definition of these types has to be stored in <choral_home>/data/types/ folder as a <molecule_type_name>.type file. The type files planned to use by the cartridge must be created before the Initialize step
Initialize the server
Before initializing the server always check the config/application.properties file.
Be sure the user name with System privileges is correct, the server host name, port, and choral callback user name are the intended ones.
Also set up the molecule types, because they can’t be changed later.
Initialization needs empty /data/store/ folder, consequently already existing index data cannot be preserved if server initialization must be repeated.
Re-indexing will be required.
Two methods can be followed in order to initialize the server by running the following command as superuser on Windows, choral user on Linux:
Initialization with SQL script execution
Windows (in an administrator terminal):
sudo -u choral ./init-choral
When prompted for password, type the password.
Initialization without SQL script execution
sudo -u choral ./init-choral-service
In case the second method is followed, the steps described in section Prepare Choral environment in Oracle must also be executed.
run-choral.exe (on Windows)
run-choral.sh (on linux)
On linux if the deb or rpm installer was applied, the next initialization method is also applicable:
stop | status switches also work.
on Windows, run as administrator: install_service.bat (name of the service is JChem Choral Cartridge, set up as any windows service from this step, can be uninstalled by uninstall_service.bat)
on linux: choral-service.sh (set it up according to your operating system. The deb and rpm installers will also do this step.)
If the second initalization method was followed, run the sql files provided by the initialization
Run the following sql files present in sql folder in the following order:
Prerequisite: the server is running
It is advised not to use the choral_owner schema for any other purpose than maintaining the cartridge (e.g. don’t store your business data in this schema).
Molecule types define the interpretation mode of the chemical structures. The definition of these types has to be stored in
<choral_home>/data/types/ folder (Linux) or
C:\Program Files\ChemAxon\choral\data\types\ (Windows) as a <molecule_type_name>.type file. You can add, modify, delete molecule type files according to your needs.
We provide a sample type, see file
<choral_home>/data/types/sample.type (Linux) or
C:\Program Files\ChemAxon\choral\data\types\sample.type (Windows).
The following settings can be defined in a <molecule_type_name>.type file:
Standardizer action string must follow the syntax of command line standardizer actions:
Standardizer configuration file can be created as described in Creating a Configuration Standardizer page.
The types stored in <choral_home>/data/types/ are loaded when the choral service is initialized. Therefore, if you add a new molecule type or change an existing one, the following steps have to be executed:
<choral_home>/data/store/ (Linux) or
Further users can be created, like table owner users, searcher users.
Grant the necessary privileges to TABLE_OWNER and SEARCH users through ROLES (specified in the application.properties file).
The following grants must be separately repeated for each molecule type present in /data/types/ folder when the service was initialized.
Execute privileges must be granted to table owners for creating <type>_idxtype domain indexes.
Execute privileges must be granted to table owners and searcher users for using the <type>_search and <type>_relevance operators (that is privileges for searching).
Further execute privileges can added optionally to the appropriate user:
As table owner, you must give select privileges on your table(s) to searcher users.
There are no known restrictions using synonyms. Granting privileges is still required according to the Oracle privilege handling logic.
Here are some examples:
In the case of these examples you can simplify your SQL statements by doing the following:
You can replace "<choral_owner>.sample_idxtype" with "sample_idxtype" when logged in as TABLE_OWNER.
You can replace "<choral_owner>.sample_search" and "<choral_owner>.sample_relevance" with "sample_search" and "sample_relevance" respectively when logged in as SEARCHER.
After replacing coral_owner with your installed choral owner's name, the following query will check whether the system is working fine:
The query must return 1 row.
Stop using the Cartridge.
In case of changing the port:
Change the server.port property in the application.properties file
In case of changing the machine/IP address:
Check the IP of the (new) JChem server which the database can connect to. A simple way to do it is to log in to the database from the new machine and call:
In case of changing the machine/IP address:
log in as choral_owner to the database and run the following script:
In case of changing the port:
Log in as choral_owner to the database and run the following script:
upper_portaccordingly in the file
/sql/2_http.sqland run 2_http.sql as SYSTEM user.
choral.init.useJobs, This setting can be changed later by doing the following:
Change from true to false:
Change the following setting as CHORAL_OWNER.
You can also revoke the grant to create jobs from the CHORAL_OWNER.
Change from false to true:
The create job privilege must be given to the CHORAL_OWNER (if it was missing)
The parallel batch count parameter must be set to greater than one (10 is the default at installation).
Logging of the Oracle side of Choral cartridge is described here.
Logging level can be overridden for the current session as well.
TABLE level: INFO
DBMS_OUTPUT level: ERROR
Drop the choral owner.
Uninstall the created service or remove the extracted folder created at the install. Remove the data and logs folders if they were configured.