# tSemanticMatch

Availability-note[Beta](https://help.talend.com/r/en-US/Cloud/labels-on-talend-help-center/availability-beta)

Beta content

Enables semantic similarity search against a vector database using an input column as the query vector.

## Semantic matching and traditional matching

Traditional duplicate detection relies on exact matches or pattern rules. For example, finding records where "company name" is identical or within a Levenshtein distance of 2.

Semantic matching compares the meaning of data using vector embeddings. Two product listings, one labeled "32-inch 4K smart television" and another "UltraHD smart TV 32 inch", are semantically identical even though the text differs completely. Semantic matching catches these fuzzy duplicates automatically without hard-coded rules.

Benefits of semantic matching:

* Handles synonyms: "car" and "automobile" match despite different words.
* Captures intent: "lightweight laptop" and "portable computer" are semantically similar.
* No rule maintenance: Uses learned representations instead of manual patterns.
* Scalable: Works with large datasets and complex product hierarchies.

## How tSemanticMatch works

tSemanticMatch performs the following workflow:

1. Takes an input record containing a search column; text or structured data.
2. Uses that column as a query vector to search a vector database for similar records.
3. Returns the closest matches along with similarity scores.
4. Outputs records based on a score threshold: records with scores above the threshold pass to the Flow output; records below the threshold are rejected.

The component outputs the original input columns, the matched record details, and a similarity score for each match.

## Vector database integration

tSemanticMatch currently only integrates with Milvus, a high-performance vector database optimized for similarity search. Milvus stores and indexes vector embeddings, allowing fast retrieval of similar records at scale.

## Supported vector types

tSemanticMatch only supports FloatVector for semantic similarity search. Sparse and binary vectors are not supported. You must provide or generate FloatVector as input to the component. If you need to use a different vector type, convert it to FloatVector before passing it to tSemanticMatch.

For example, you can use tEmbeddingAI to generate FloatVector embeddings from text data for semantic search operations.

## Input and output schema

tSemanticMatch adds two columns to the input and Flow output schema:

* MATCH\_RESULT: The text or record content from the matching vector, retrieved using the configured text field name.
* SCORE: A similarity score (0.0-1.0) where 1.0 is a perfect match.

If no match is found or the score falls below the minimum threshold, the record is returned in the Reject output.

## tSemanticMatch Standard Properties

These properties are used to configure tSemanticMatch running in the Standard Job framework.

The Standard tSemanticMatch component belongs to the AI family.

Information noteNote: This component is available from Talend Studio 8.0 R2026-06.

## Basic settings

| Properties | Description |
| --- | --- |
| Schema and Edit Schema | <ul> <li> <p>A schema is a row description. It defines the number of fields            (columns) to be processed and passed on to the next component. When you create a Spark            Job, avoid the reserved word <kbd>line</kbd> when naming the            fields.</p> <p>Click <span>Edit        schema</span> to make changes to the schema. If the current schema is of the <span>Repository</span> type, three options are available:</p> <ul> <li> <p> <span>View schema</span>: choose this                option to view the schema only.</p> </li> <li> <p> <span>Change to built-in property</span>:                choose this option to change the schema to <span>Built-in</span> for local changes.</p> </li> <li> <p> <span>Update repository connection</span>:                choose this option to change the schema stored in the repository and decide whether                to propagate the changes to all the Jobs upon completion.</p> <p>If you just want to                propagate the changes to the current Job, you can select <span>No</span> upon completion and choose this schema metadata                again in the <span>Repository Content</span>                window.</p> </li> </ul> <p>This component offers the advantage of the                  dynamic schema feature. This allows you to retrieve unknown columns from source                  files or to copy batches of columns from a source without mapping each column                  individually. For further information about dynamic schemas, see <a href="https://help.qlik.com/talend/r/en-US/8.0/studio-user-guide/dynamic-schema" target="_blank">Dynamic schema</a>.</p> <p>This            dynamic schema feature is designed for the purpose of retrieving unknown columns of a            table and is recommended to be used for this purpose only; it is not recommended for the            use of creating tables.</p> </li> <li> <p> <span>Built-In</span>: You create and store the schema locally for this component                only.</p> </li> <li> <p> <span>Repository</span>: You have already created the schema and stored it in the                Repository. You can reuse it in various projects and Job designs.</p> </li> </ul> |
| Search column | The input column used as the query vector for searching. Select a column containing a<br>FloatVector. This column's vector representation must be a FloatVector compatible with<br>the vector field in the database. Sparse and binary vectors are not supported. |
| Vector DB | Select the vector database. |
| URI | Enter the endpoint URI in double quotes. For example,<br>http://milvus-server:19530 or<br>https://cloud-milvus.example.com. |
| Token | Enter the authentication token or API key required by your database. Leave blank if<br>it runs without authentication. |
| Database | Enter the name of the database containing your vector collection. |
| Collection | Select the collection that stores the vector embeddings and associated data. |
| Vector field | Select the field in the collection storing vector embeddings. |
| Text field | This setting is optional.<br><br>Select the field in the collection containing human-readable text or content. If<br>specified, this text is returned in the MATCH\_RESULT output<br>column. If not specified, only the score is returned. |
| Max results | Enter the maximum number of matching records to return per input record. Set to 1 for<br>single match. Increase for multiple matches. |
| Min score | Enter the minimum similarity score threshold. The value must be in the range<br>0.0-1.0.<br><br>Records with scores below this value are returned in the reject output. For example,<br>0.6 means only records 60% similar or better are accepted. |

## Advanced settings

| Properties | Description |
| --- | --- |
| tStatCatcher Statistics | Select this checkbox to gather the Job processing metadata at the Job level<br>as well as at each component level. |
| Primary key | Select the field that uniquely identifies each record in the collection. This value is returned in the output to allow you to trace matches back to source records. |
| Metadata filter | Select the checkbox to define filter conditions with an operator and a value. The<br>available operators depend on the vector database, not Talend Studio.<br><br>The IN operator lets you define the exact values your data<br>must match. For example: price<br>IN<br>750,1000,1500 means that the value of the field price must be<br>750, 1000, or 1500. Any other value will be rejected. |

## Global Variables

| Variables | Description |
| --- | --- |
| Global Variables | ERROR\_MESSAGE: the error message generated by the<br>component when an error occurs. This is an After variable and it returns a string. This<br>variable functions only if the Die on error checkbox is<br>cleared, if the component has this checkbox. |