Skip to main content
Version: 2026.0

JoinQueryBuilder

A special pattern builder that allows to join and filter index documents based on the content of other documents in another index group.

The join pattern requires two fields on which the join is applied. Only documents with matching values in both fields are joined. from describes the index group which will be joined. The specified field is used as key for the join. to describes the field of the searched index group, which is used to find matching documents of the joined index group. The pattern is only applied on the joined index group and does the actual filtering.

IMPORTANT: The fields used for the join must share compatible index field types. Such as STRING -> STRING, TEXT ->TEXT, TEXT_PLAIN -> TEXT, BOOLEAN -> BOOLEAN.

Most text-based types can be used together, but unexpected results may occur depending on the content, e.g. if only one of the fields contains stop words. The safest way is to always use only two fields of the same type.

Methods​

asNestedPattern​

asNestedPattern(): NestedPattern

Wraps this builder in to NestedPattern term object that can be appended to a pattern config instance.

Returns​

NestedPattern

a new NestedPattern instance that holds pattern of this builder.

isEmpty​

isEmpty(): boolean

Checks if the join query contains no patten and is thus considered empty.

Returns​

boolean

true, if the builder contains no pattern.

setFrom​

setFrom(pIndexGroup, pIndexField): JoinQueryBuilder

Specifies the 'from' field of the joined index group used to find matching documents.

The function uses the index group and respective index fields directly to set the 'from' field.

from describes the index group which will be joined. The specified field is used as key for the join. to describes the field of the searched index group, which is used to find matching documents of the joined index group.

Only documents with matching values in both field are joined.

Parameters​

pIndexGroup
string | number | boolean

the name of the searched index group that the field belongs to.

pIndexField
string | number | boolean

the name of the index field.

Returns​

JoinQueryBuilder

Example​

// Examples to show how the field names can be specified.
var joinQ = indexsearch.createJoinQuery();

// Specify with the default field name mapping (entity field in lowercase)
// - This results in the '_value' variant to be used if present, otherwise the '_displayvalue' field is used.
joinQ.setFrom("Person", "lastname");

// Specify with the default field name mapping with value suffix.
// - Valid options are '_value' and '_displayvalue' for the respective mapped entity field options.
joinQ.setFrom("Person", "lastname_value");

// Specify with the field with the index group prefix.
// - Works the same way as when the prefix is omitted.
joinQ.setFrom("Person", "person_lastname");

// Specify with the field with the index group prefix and value suffix.
// - Works the same way as when the prefix is omitted.
joinQ.setFrom("Person", "person_lastname_value");

// Specify with a system field of the index.
joinQ.setFrom("Person", "_local_id_");

// Specify with a system field using the respective constant.
joinQ.setFrom("Person", indexserach.FIELD_ID);

setFromEntity​

setFromEntity(pEntity, pEntityField): JoinQueryBuilder

Specifies the 'from' field of the joined index group used to find matching documents.

The function uses the entity and respective entity fields to set the 'from' field. During the build of the join query the corresponding index group and field will be looked up internally.

from describes the index group which will be joined. The specified field is used as key for the join. to describes the field of the searched index group, which is used to find matching documents of the joined index group.

Only documents with matching values in both field are joined.

Parameters​

pEntity
string | number | boolean

the identifier of the entity the field and searched index group belongs to.

pEntityField
string | number | boolean

the name of the entity field.

Returns​

JoinQueryBuilder

Example​

// Examples to show how the entity field names can be specified.
var joinQ = indexsearch.createJoinQuery();

// Specify with the entity field name.
// - This results in the '.value' variant of the index field to be used if present, otherwise the '.displayValue' index field is used.
joinQ.setFromEntity("Person_entity", "LASTNAME");

// Specify with the entity field name including the '.value' or '.displayValue' suffix.
joinQ.setFromEntity("Person_entity", "LASTNAME.value");

setFromEntityWithIndexField​

setFromEntityWithIndexField(pEntity, pIndexField): JoinQueryBuilder

Specifies the 'from' field of the joined index group used to find matching documents.

The function uses the entity and direct index fields to set the 'from' field. During the build of the join query the corresponding index group will be looked up internally. This function is useful if system fields of the index are required, that do not have an explicit mapping for the entity.

from describes the index group which will be joined. The specified field is used as key for the join. to describes the field of the searched index group, which is used to find matching documents of the joined index group.

Only documents with matching values in both field are joined.

Parameters​

pEntity
string | number | boolean

the name of the entity the searched index group belongs to.

pIndexField
string | number | boolean

the name of the index field.

Returns​

JoinQueryBuilder

Example​

// Examples to show how the index field names can be specified with the entity.
var joinQ = indexsearch.createJoinQuery();

// Specify with a system field of the index.
joinQ.setFromEntityWithIndexField("Person_entity", "_local_id_");

// Specify with a system field using the respective constant.
joinQ.setFromEntityWithIndexField("Person_entity", indexserach.FIELD_ID);

setPattern​

setPattern(pPattern): JoinQueryBuilder

Specifies the index pattern used to search and filter the documents of the joined index group.

Parameters​

pPattern
string | number | boolean

the index pattern as string.

Returns​

JoinQueryBuilder

setTo​

setTo(pIndexGroup, pIndexField): JoinQueryBuilder

Specifies the 'to' field of the searched documents used as key to find matching documents in the joined index group.

The function uses the index group and respective index fields directly to set the 'to' field.

from describes the index group which will be joined. The specified field is used as key for the join. to describes the field of the searched index group, which is used to find matching documents of the joined index group.

Only documents with matching values in both field are joined.

Parameters​

pIndexGroup
string | number | boolean

the name of the joined index group that the field belongs to.

pIndexField
string | number | boolean

the name of the index field.

Returns​

JoinQueryBuilder

Example​

// Examples to show how the field names can be specified.
var joinQ = indexsearch.createJoinQuery();

// Specify with the default field name mapping (entity field in lowercase)
// - This results in the '_value' variant to be used if present, otherwise the '_displayvalue' field is used.
joinQ.setTo("Person", "lastname");

// Specify with the default field name mapping with value suffix.
// - Valid options are '_value' and '_displayvalue' for the respective mapped entity field options.
joinQ.setTo("Person", "lastname_value");

// Specify with the field with the index group prefix.
// - Works the same way as when the prefix is omitted.
joinQ.setTo("Person", "person_lastname");

// Specify with the field with the index group prefix and value suffix.
// - Works the same way as when the prefix is omitted.
joinQ.setTo("Person", "person_lastname_value");

// Specify with a system field of the index.
joinQ.setTo("Person", "_local_id_");

// Specify with a system field using the respective constant.
joinQ.setTo("Person", indexserach.FIELD_ID);

setToEntity​

setToEntity(pEntity, pEntityField): JoinQueryBuilder

Specifies the 'to' field of the searched documents used as key to find matching documents in the joined index group.

The function uses the entity and respective entity fields to set the 'to' field. During the build of the join query the corresponding index group and field will be looked up internally.

from describes the index group which will be joined. The specified field is used as key for the join. to describes the field of the searched index group, which is used to find matching documents of the joined index group.

Only documents with matching values in both field are joined.

Parameters​

pEntity
string | number | boolean

the name of the entity the joined index group belongs to.

pEntityField
string | number | boolean

the name of the entity field.

Returns​

JoinQueryBuilder

Example​

// Examples to show how the entity field names can be specified.
var joinQ = indexsearch.createJoinQuery();

// Specify with the entity field name.
// - This results in the '.value' variant of the index field to be used if present, otherwise the '.displayValue' index field is used.
joinQ.setToEntity("Person_entity", "LASTNAME");

// Specify with the entity field name including the '.value' or '.displayValue' suffix.
joinQ.setToEntity("Person_entity", "LASTNAME.value");

setToEntityWithIndexField​

setToEntityWithIndexField(pEntity, pIndexField): JoinQueryBuilder

Specifies the 'to' field of the searched documents used as key to find matching documents in the joined index group.

The function uses the entity and direct index fields to set the 'to' field. During the build of the join query the corresponding index group will be looked up internally. This function is useful if system fields of the index are required, that do not have an explicit mapping for the entity.

from describes the index group which will be joined. The specified field is used as key for the join. to describes the field of the searched index group, which is used to find matching documents of the joined index group.

Only documents with matching values in both field are joined.

Parameters​

pEntity
string | number | boolean

the name of the entity the joined index group belongs to.

pIndexField
string | number | boolean

the name of the index field.

Returns​

JoinQueryBuilder

Example​

// Examples to show how the index field names can be specified with the entity.
var joinQ = indexsearch.createJoinQuery();

// Specify with a system field of the index.
joinQ.setToEntityWithIndexField("Person_entity", "_local_id_");

// Specify with a system field using the respective constant.
joinQ.setToEntityWithIndexField("Person_entity", indexserach.FIELD_ID);

Example​

<code>// In this example a index query is created that retrieves
// all organisations for which a open offer exists in the index.

// 1. Create a query object for the actual search.
var indexQuery = indexsearch.createIndexQuery()
 .setIndexGroups(["Organisation"]); // set the required index group.

// 2. Create a join query builder that joins organisation with the offer group.
// - In order to work the appropriate 'from' and 'to' fields must be specified.

// 2a. Creates the join query using the respective index groups and fields.
// - The first parameter for 'from' and 'to' is the identifier of the index group
// - The second parameter is index field of the group used for joining.
// -- For the field system field of the index, e.g. 'indexsearch.FIELD_ID' can be used.
//    Otherwise the plain name of field 'organisation_contact_id' can be used or with the respective suffixes
//    '_value' and '_displayvalue' to distinguish between teh to field variants if needed. (default is '_value')
var joinQ = indexsearch.createJoinQuery()
 .setFrom("Offer", "organisation_contact_id") // the field in the target group on which to join.
 .setTo("Organisation", indexsearch.FIELD_ID) // the field that is used to join.
 .setPattern("statuscode:OPEN"); // the pattern that is applied to filter on the target group

// 2b. Creates the same join query using the entity and the respective entity fields or index system fields.
// - The first parameter is the name of the entity that defines the indexgroup.
// - For the 'setFromEntity' and 'setToEntity' functions, the second parameter is the name of the entity field
//   whose corresponding index field is used.
// - For the 'setFromEntityWithIndexField' and 'setToEntityWithIndexField', the second parameter is the name of the index field.
     This allows to specify a system field, e.g. 'indexsearch.FIELD_ID', in combination with the entity.
var joinQEntity = indexsearch.createJoinQuery()
 .setFromEntity("Offer_entity", "OrganisationContactId.value") // the field in the target group on which to join.
 .setToEntityWithIndexField("Organisation_entity", indexsearch.FIELD_ID) // the field that is used to join.
 .setPattern("statuscode:OPEN"); // the pattern that is applied to filter on the target group

// 3. Add the final join query as a filter pattern for the actual search.
indexQuery.addFilter(indexsearch.buildPattern(joinQ));
indexserach.searchIndex(indexQuery);
</code>