# Full-text Engine (Engine `vtx`)

The full-text engine serves for processing full-text requests of the clients.

The OSFTS engine is supported, which is often also called the "Lucene engine" or simply "osfts".
For existing installations, other full-text connections are still supported.

In each job description, the supported engines are noted as a short name, indicating which full-text engine supports the job.
If a full-text engine does not support a job, the execution has no effect and an empty result set is returned if applicable.

* [vtx.CloseQuery](vtx.md#vtx.CloseQuery)
* [vtx.GetAutoCompleteResult](vtx.md#vtx.GetAutoCompleteResult)
* [vtx.GetEngineName](vtx.md#vtx.GetEngineName)
* [vtx.GetMaxHits](vtx.md#vtx.GetMaxHits)
* [vtx.GetSearchResult](vtx.md#vtx.GetSearchResult)
* [vtx.GetSimilarDMSObjects](vtx.md#vtx.GetSimilarDMSObjects)
* [vtx.IsOntologySearchEnabled](vtx.md#vtx.IsOntologySearchEnabled)
* [vtx.IsSearchForSimilarDMSObjectsEnabled](vtx.md#vtx.IsSearchForSimilarDMSObjectsEnabled)
* [vtx.OpenObjectQuery](vtx.md#vtx.OpenObjectQuery)

## Undocumented Endpoints

The following jobs are offered by the enaio® server in the `vtx` engine but are not currently described in this documentation:

Auto-complete and suggest::
`vtx.IsAutoCompleteEnabled`, `vtx.IsSuggestEnabled`

Search results and document retrieval::
`vtx.GetDocument`

Query variants::
`vtx.OpenWordListQuery`

Feature flags::
`vtx.IsFacetSearchEnabled`, `vtx.IsPreviewEnabled`

Client management::
`vtx.CleanupClient`

<a id="vtx.CloseQuery"></a>

## vtx.CloseQuery

This job closes a query identified by a GUID and frees resources.

### Input Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `Flags` | INT | Yes | Currently not supported — pass `0`. |
| `Guid` | STRING | Yes | GUID of the query (see output parameter `Guid` in [vtx.OpenObjectQuery](vtx.md#vtx.OpenObjectQuery)) |

### Return Value

(INT): 0 = Job successful, otherwise error code.

> **Note:** Supported engines: `lu`, `rw`

<a id="vtx.GetAutoCompleteResult"></a>

## vtx.GetAutoCompleteResult

This job returns auto-complete suggestions from the full-text engine for a search term.
Typically used in the search input field to display live suggestions.

====
This job is not described in the official enaio® documentation but is listed as known in the VTX engine overview's "Undocumented Endpoints" section. This description was reconstructed from the call code of the `enaio-jobs-custom` template.
====

### Input Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `Flags` | INT | Yes | Reserved; always pass `0`. |
| `Term` | STRING | Yes | Input term for which suggestions are to be returned. |
| `[ObjectTypes]` | STRING | No | Restrict suggestions to specific object types. Format: separator-separated list of numeric object type IDs (the separator is passed through unchanged by the call code — typically `,` or `;`). |

### Output Parameters

| Name | Type | Dependency | Description |
|---|---|---|---|
| `Result` | STRING | — | Suggestion list in the format `term1,score1;term2,score2;…`. Individual hits are separated by `;`; `term` and `score` are separated by `,`. |

### Return Value

`(INT)`: `0` = job successful, otherwise error code.

### See Also

* `vtx.IsAutoCompleteEnabled` — feature flag query (likewise officially undocumented)
* [vtx.GetSearchResult](vtx.md#vtx.GetSearchResult) — actual full-text search

<a id="vtx.GetEngineName"></a>

## vtx.GetEngineName

This job delivers the short name of the full-text engine (e.g., `ms` for Microsoft SQL Server full-text) from the registry (path `VTX`→`Engine`).

### Input Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `Flags` | INT | Yes | Currently not supported — pass `0`. |

### Output Parameters

| Name | Type | Dependency | Description |
|---|---|---|---|
| `Result` | STRING | — | Short name of the full-text engine |

### Return Value

(INT): 0 = Job successful, otherwise error code.

> **Note:** Supported engines: all

<a id="vtx.GetMaxHits"></a>

## vtx.GetMaxHits

This job delivers the server-side configured upper limit for the maximum hit count in full-text searches.
When calling all full-text search jobs, it should be ensured that the hit limit specified there is not greater than the server-side configured maximum.

### Output Parameters

| Name | Type | Dependency | Description |
|---|---|---|---|
| `Result` | INT | — | Server-side configured upper limit for the maximum hit count |

### Return Value

(INT): 0 = Job successful, otherwise error code.

> **Note:** Supported engines: all

### See Also

[vtx.OpenObjectQuery](vtx.md#vtx.OpenObjectQuery), [vtx.GetSimilarDMSObjects](vtx.md#vtx.GetSimilarDMSObjects)

<a id="vtx.GetSearchResult"></a>

## vtx.GetSearchResult

This job performs a full-text search via the VTX engine and returns hits with score, optional preview and optional facet aggregations.
Request and response are exchanged as JSON.

====
This job is not described in the official enaio® documentation but is listed as known in the VTX engine overview's "Undocumented Endpoints" section. This description was reconstructed from the call code of the `enaio-jobs-custom` template.
====

### Input Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `Flags` | INT | Yes | Reserved; always pass `0`. |
| `Query` | BASE64 | Yes | Search request as a UTF-8-encoded JSON document (schema below). |

#### `Query` JSON schema

```json
{
  "searchString": "<search term>",
  "maxHits": 50,
  "restrictions": {
    "objectTypeIds": [<int>, ...],
    "prefetchedIds": [<int>, ...],
    "locations": [
      { "objectTypeId": <int>, "objectId": <int> },
      ...
    ]
  },
  "flags": {
    "includePreview": true,
    "includeFacets": true
  },
  "aggregations": {
    "filter": {
      "<facetKey>": ["<value>", ...]
    }
  },
  "queryCatalogueLocale": "<locale tag, e.g. de_DE>"
}
```
| Field | Type | Required | Description |
|---|---|---|---|
| `searchString` | string | Yes | Search term; must not be empty. |
| `maxHits` | int | Yes | Upper bound of hits; call-code default `50`. |
| `restrictions.objectTypeIds` | int[] | Yes | List of allowed object types; at least one entry. |
| `restrictions.prefetchedIds` | int[] | No | Pre-restricted object IDs (re-ranking instead of search). |
| `restrictions.locations` | obj[] | No | List of {`objectTypeId`,`objectId`} pairs to restrict to specific parents (folders / registers). |
| `flags.includePreview` | bool | No | Generate snippet previews. |
| `flags.includeFacets` | bool | No | Compute facet aggregations alongside hits. |
| `aggregations.filter` | map | No | Active facet filters per facet key. |
| `queryCatalogueLocale` | string | No | Language for catalog lookups. |

### Output Parameters

| Name | Type | Dependency | Description |
|---|---|---|---|
| `Result` | BASE64 | — | Response as UTF-8-encoded JSON. |

#### `Result` JSON schema

```json
{
  "totalHits": <int>,
  "hits": [
    {
      "objectTypeId": <int>,
      "objectId": <int>,
      "score": <number>,
      "previewSnippet": "<text>"
    },
    ...
  ],
  "aggregations": {
    "<facetKey>": {
      "buckets": [
        { "key": "<value>", "doc_count": <int> },
        ...
      ]
    }
  }
}
```

### Return Value

`(INT)`: `0` = job successful, otherwise error code.

### See Also

* [vtx.GetAutoCompleteResult](vtx.md#vtx.GetAutoCompleteResult) — live suggestions for the search input
* [vtx.OpenObjectQuery](vtx.md#vtx.OpenObjectQuery) — alternative request variant via object selector
* `vtx.IsFacetSearchEnabled` / `vtx.IsPreviewEnabled` — feature flag queries (likewise officially undocumented)

<a id="vtx.GetSimilarDMSObjects"></a>

## vtx.GetSimilarDMSObjects

This job delivers a list of other objects whose textual content is similar to the passed object.

> **Note:** This similarity search is currently only supported when using OSFTS as the full-text engine, configured with analyzer `intrafind` there, and the license OKM is present.
Whether the search is supported can be determined with [vtx.IsSearchForSimilarDMSObjectsEnabled](vtx.md#vtx.IsSearchForSimilarDMSObjectsEnabled).

### Input Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `ObjectID` | INT | Yes | ID of the DMS object for which similar objects should be searched |
| `[MaxHits]` | INT | No | Maximum number of hits to be returned. If the parameter is not passed, the maximum hit count is determined based on registry entries. |

### Output Parameters

| Name | Type | Dependency | Description |
|---|---|---|---|
| `Result` | STRING | — | Found documents as semicolon-separated list; each entry consists of object ID, object type, ranking, and hit ID (comma-separated). |

### Return Value

(INT): 0 = Job successful, otherwise error code.

> **Note:** Supported engines: `lu`

### See Also

[vtx.IsSearchForSimilarDMSObjectsEnabled](vtx.md#vtx.IsSearchForSimilarDMSObjectsEnabled)

<a id="vtx.IsOntologySearchEnabled"></a>

## vtx.IsOntologySearchEnabled

This job indicates whether the full-text engine supports searching for similar terms (ontological search).

### Output Parameters

| Name | Type | Dependency | Description |
|---|---|---|---|
| `Result` | BOOL | — | `1` = search for similar terms is supported; `0` = not supported |

### Return Value

(INT): 0 = Job successful, otherwise error code.

> **Note:** Supported engines: all. Currently returns `1` only for engine `lu`.

### See Also

[vtx.OpenObjectQuery](vtx.md#vtx.OpenObjectQuery)

<a id="vtx.IsSearchForSimilarDMSObjectsEnabled"></a>

## vtx.IsSearchForSimilarDMSObjectsEnabled

This job indicates whether the full-text engine supports searching for DMS documents with similar content.

### Output Parameters

| Name | Type | Dependency | Description |
|---|---|---|---|
| `Result` | BOOL | — | `1` = similarity search is supported; `0` = not supported |

### Return Value

(INT): 0 = Job successful, otherwise error code.

> **Note:** Supported engines: all. Currently returns `1` only for engine `lu`.

### See Also

[vtx.GetSimilarDMSObjects](vtx.md#vtx.GetSimilarDMSObjects)

<a id="vtx.OpenObjectQuery"></a>

## vtx.OpenObjectQuery

This job performs a query for an object and returns the result.

> **Note:** Ontological search (`ONTOLOGY=1` in the Query parameter) is currently only supported when using OSFTS as the full-text engine, configured with analyzer `intrafind` there, and the license OKM is present.
Whether the search is supported can be determined with [vtx.IsOntologySearchEnabled](vtx.md#vtx.IsOntologySearchEnabled). +
When using OSFTS with `intrafind`, the LIS license must also be present in general — otherwise the job call returns error code `-1042674726` (see [Error Codes](errorcodes.md)).

### Input Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `Flags` | INT | Yes | Flags to be passed to the full-text engine |
| `Query` | STRING | Yes | Query in INI format (see example below) |
| `[MessageLanguageId]` | INT | No | Windows language ID for the language in which a returned message (return value `Message`) should be written (e.g., `7` = German) |

### Output Parameters

| Name | Type | Dependency | Description |
|---|---|---|---|
| `Result` | STRING | — | Found documents as semicolon-separated list; each entry consists of object ID, object type, ranking, and hit ID (comma-separated). |
| `Guid` | STRING | — | GUID of the query (for [vtx.CloseQuery](vtx.md#vtx.CloseQuery)) |
| `[AlternativeQuerySuggestion]` | STRING | Optional | Suggestion for alternative search terms. Only returned when using OSFTS as full-text engine and an alternative suggestion is available. |
| `[OntologyTerms]` | STRING | Optional | List of related search terms in the format `term,similarity%;…` (e.g., `horse,55;travel,43;vacation,12`). Only returned when `ONTOLOGY=1` is set in the query. |
| `[Message]` | STRING | Optional | Message about the search result |

### Example

When using Microsoft SQL Server, only the first three lines of the `[PAGE00]` section are needed.

```ini
[PAGE00]
#OSTYPE#=262144
FULLTEXT=horse
ONTOLOGY=1
#OSACT#=1
FELD0=#OSPOS000#;Author;field1;X;50;0;0
FELD1=#OSPOS001#;Source;field2;X;150;0;0
FELD2=#OSPOS002#;Text2;field3;X;50;0;0
[PDMSPParams]
EXPANSION_LEVEL_PROPERTY=4
FUZZY_SPELL_HALF_WORDS=FALSE
FUZZY_SPELL_THRESHOLD=0
MAX_FUZZY_SPELL_PROPERTY=15
MAX_REG_EXPR_PROPERTY=50
WARN_MAX_REG_EXPR_PROPERTY=FALSE
WORD_EXPANSION_LIMIT_PROPERTY=20
LMPI_SET_LANG_PROPERTY=de
MAX_DOCS_PROPERTY=999
RwareQueryType=P
OSQueryType=Object
OSSelectedTypes=current
```

### Return Value

(INT): 0 = Job successful, otherwise error code (e.g., `-1042674726`, when using OSFTS with `intrafind` and the LIS license is missing).

> **Note:** Supported engines: all

### See Also

[vtx.IsOntologySearchEnabled](vtx.md#vtx.IsOntologySearchEnabled)