Designating database fields to be indexed

CollectionSpace provides you with two ways you can designate which database fields that are to be indexed.

In combination, this gives you a mechanism - independent of any configuration settings for any database type or instance - to specify that certain fields (columns) in the database should always be indexed. These indexes will be checked for and, if needed, created automatically, every time you start your CollectionSpace system.

Designating fields to be indexed via per-tenant configuration

In summary, you can designate fields to be indexed by adding entries to a configuration file within your museum's (aka your "tenant's") folder, in the Services layer source code tree, specifying the schema(s) and field(s) which are to be indexed.

You can then run a command to copy ("deploy") your configuration changes to the relevant directories on the server. After doing so, the next time that you start the CollectionSpace servers, the indexes for the fields you've designated will automatically be created in the database, if they don't already exist. They'll also be checked for - and if this ever becomes necessary, re-created - at every subsequent system startup, as well.

Here are the specifics of how you do this:

Within the source code folder for CollectionSpace's Services layer, find the folder containing the configuration file for your museum ("tenant"). For details on how to set up your tenant and on finding this folder, please see Creating your new tenant.
In this folder, edit the configuration file for your tenant, tenant-bindings.delta.xml
In that file, add a new entry for each new index you wish to have created, specifying the table and field names on which you'd like to create the index. See Creating new entries for fields to be indexed, below, for details.
Copy (deploy) your changes to the CollectionSpace server folder.
Within the folder in which you've checked out the Services source code, at your system's Terminal or command prompt:
- Navigate (change) to the services/common folder (sub-directory), within that source code folder.
- From within that folder, enter:
```
ant deploy_tenantconfig
```
At any time after deploying your configuration changes, to make the CollectionSpace system create new database indexes, shut down and then start up the CollectionSpace servers.

Creating new entries for fields to be indexed

When creating new configuration entries, designating fields to be indexed, it can be helpful to start out by looking at existing configuration entries.

You can find these entries in tenant-bindings-proto.xml, the default configuration file that comes with CollectionSpace, and whose settings are inherited by all museums (tenants) on a CollectionSpace system, except for those settings overridden on a per-tenant basis.

Below is an example of a block of configuration within that file, that designates that indexes are to be created on three different fields (columns) within the default Person record:

<tenant:serviceBindings id="Persons" name="Persons" type="authority" version="0.1">
...
    <service:initHandler xmlns:service="http://collectionspace.org/services/config/service">
        <service:classname>org.collectionspace.services.common.init.AddIndices</service:classname>
        <service:params>
            <service:field>
                <service:table>persons_common</service:table>
                <service:col>inauthority</service:col>
            </service:field>
            <service:field>
                <service:table>persontermgroup</service:table>
                <service:col>termdisplayname</service:col>
            </service:field>
            <service:field>
                <service:table>persons_common</service:table>
                <service:col>shortidentifier</service:col>
            </service:field>
        </service:params>
    </service:initHandler>

Note that in two of the <service:field> entries above, the fields (columns) can be found in the main table for the Person record, persons_common. In a third entry, however, where the termdisplayname field (column) was part of the repeatable (multivalued) Term Information Group, the relevant field was found in a different table, persontermgroup. (In general, repeatable fields or fields in repeatable groups will be found in separate tables in the database, rather than in the main table for a particular type of record.)

Now that you have an example of how to designate fields to be indexed, you'll then need to add similar XML markup to your own tenant's configuration file, so that when merged in with CollectionSpace's default configuration file, this will cause your own entries to be inserted at the appropriate place(s) in the merged configuration file.

In summary:

You'll need to make the following changes within your own tenant's configuration file. (You can find this file in the services layer source code tree, in services/common/src/main/cspace/config/services/tenants/{your_tenant_identifier}/tenant-bindings.delta.xml)

If CollectionSpace's default configuration file, tenant-bindings-proto.xml, does not already contain a <service:initHandler ...> block within the configuration for the type of record whose field(s) you'd like to index, you'll need to make the following changes within your own tenant's configuration file:
- Create that entire <service:initHandler ...> block.
- Within that block, add one or more <service:field> entries, one for each field on which you want to create a new index.
- Via XmlMerge annotations, identify that that block is to be merged underneath that record's topmost element, <tenant:serviceBindings id="{record_type_here}" ...>.

If CollectionSpace's default configuration file, tenant-bindings-proto.xml, does already contain a <service:initHandler ...> block for the relevant record type, you'll need to make the following changes within your own tenant's configuration file:
- Create one or more <service:field> entries, one for each field on which you want to create a new index.
- Via XmlMerge annotations, identify that those entries are to be merged into the appropriate place(s) within that <service:initHandler ...> block.

Designating fields to be indexed via source code

A small set of fields, in tables used by the Nuxeo content management system and in tables used by CollectionSpace that are independent of any specific museum's ("tenant's") settings, are designated ("hard-coded") in source code as always indexed. This helps ensure that these important indexes will be created, regardless of current configuration settings.

That set of fields is currently designated in a method in the Java source code file ServiceMain, in CollectionSpace's Services layer:

https://github.com/collectionspace/services/blob/master/services/common/src/main/java/org/collectionspace/services/common/ServiceMain.java

As of this writing, the fields (table columns) that are designated in source code as always indexed in a CollectionSpace system consist of:

Table used by	Table	Column
CollectionSpace	collectionspace_core	tenantid
CollectionSpace	collectionspace_core	updatedat
Nuxeo	fulltext	jobid
Nuxeo	hierarchy	name

By editing this source code file, and rebuilding and redeploying the services layer, you can add to the set of fields that are indexed in this way. Generally, you will only want to do this if you are a software developer or otherwise are comfortable with editing and compiling source code, and have found significant benefits to adding one or more additional indexes to these types of tables. (And if you have, please post a suggestion that your changes be incorporated into the project source code, going forward, by posting a note to the project /wiki/spaces/collectionspace/pages/666276158, or by /wiki/spaces/collectionspace/pages/666274630.)

Limitations of these mechanisms

There are currently at least two notable limitations of these mechanisms for designating the fields to be indexed:

When you designate a field to be indexed for your museum ("tenant"), that field will also be indexed for all tenants in your CollectionSpace system, not just your own tenant. That will presumably change once per-tenant repositories are enabled, via a requested future functionality enhancement described in CSPACE-4979.

You can only designate that a single field (table column) is to be indexed, via the mechanisms described on this page. Creating joint indexes on two or more fields (table columns) is a requested future functionality enhancement, as described in CSPACE-4470.