Teradata Table Operators for OpenAI-Compatible Inference Servers (v1.1.1)

This package ships two Java Table Operators (TO) that let Teradata SQL call OpenAI-compatible APIs directly from queries:

• ChatCompletion – generates text via /v1/chat/completions
• Embeddings – produces numeric embeddings via /v1/embeddings

Both are suitable for:

• Enrichment data stored in Teradata with results of AI models running on inference servers
• Feature engineering workflows
• Operational pipelines requiring HTTP 429 rate-control resilience, custom headers, and optional TLS overrides

They are provider-agnostic (OpenAI, Azure OpenAI, NVIDIA Triton Inference Server, Ollama, etc.) so long as the service exposes OpenAI-compatible endpoints.

ChatCompletion and Embeddings: what they do, inputs, outputs

ChatCompletion

• What/why: Calls a chat model to transform or generate text (summaries, answers, classifications).
• Inputs:
  • Data input: table with txt column (VARCHAR or CLOB) as the prompt.
  • Optional TLS input: single-row BLOB cert for custom CA; cannot be used with IgnoreHTTPSVerification=True.
• Outputs:
  • response_txt (VARCHAR(OutputTextLength))
  • Optional diagnostics: retries_made, last_attempt_duration, rate_limit_exceeded, rate_limit_exceeded_error_details

Embeddings

• What/why: Calls an embeddings model to convert text into a numeric vector for search, RAG, clustering, etc.
• Inputs:
  • Data input: table with txt column (VARCHAR or CLOB) as the input text.
  • Optional TLS input: single-row BLOB cert for custom CA; cannot be used with IgnoreHTTPSVerification=True.
• Outputs (choose format with OutputFormat):
  • COLUMNAR (default): one FLOAT column per dimension, named by EmbeddingPrefix (default emb_0, emb_1, …).
  • BLOB: single BLOB column named embeddings with float32 bytes.
  • VARBYTE: single VARBYTE column named embeddings with float32 bytes.
  • Optional diagnostics as above.
• Notes:
  • EmbeddingLength is required and defines vector length.
  • The client enforces that the API returns at least EmbeddingLength values; otherwise it errors.
  • EmbeddingPrefix is only valid for COLUMNAR output format; providing it for BLOB/VARBYTE errors.

Parameter availability (overview)

Parameters (detailed)

Connection (both ChatCompletion and Embeddings)

Request (both ChatCompletion and Embeddings)

Headers (both ChatCompletion and Embeddings)

Rate control (both ChatCompletion and Embeddings)

Diagnostics (both ChatCompletion and Embeddings)

ChatCompletion-only

Embeddings-only

Example usage

Example Usage - Embeddings

SELECT *
FROM openai_client.Embeddings(
    ON (SELECT id, txt FROM emails.emails)
    ON (SELECT cert FROM sasha.pem_files WHERE id = 'cert') DIMENSION
    USING
        BaseURL('http://192.168.178.32:11434')
        Model('qwen2.5-coder:7b')
        ApiKey('FAKE-API-KEY')

        Delays('200,400,800')
        RetriesNumber(5)
        OutputProcessingDetails('True')
        ThrowErrorOnRateLimit('False')

        OutputFormat('BLOB')
        EmbeddingPrefix('superemb_')
        BodyParameters('metadata:{"activity": "embeddings function test"}')
) AS a;

Output

Example Usage - CompleteChat

SELECT *
FROM openai_client.CompleteChat(
    ON (SELECT id, txt FROM emails.emails)
    ON (SELECT cert FROM sasha.pem_files WHERE id = 'cert') DIMENSION
    USING
        BaseURL('http://192.168.178.32:11434')
        SystemMessage('You are the text summarizer. Summarize in ≤10 words.')
        Model('qwen2.5-coder:7b')
        ApiKey('FAKE-API-KEY')

        BodyParameters(
            'temperature:0.1',
            'max_tokens:100',
            'response_format:{"type":"json_object"}',
            'metadata:"summary_job"'
        )

        Delays('200,400,800')
        RetriesNumber(5)
        OutputProcessingDetails('True')
        ThrowErrorOnRateLimit('False')

        CustomHeaders(
            'tachyon_x: XXXXXXX',
            'tachyon_y: YYYYY'
        )
) AS a;

Output

Installation

1. Create database and grant permissions:

CREATE DATABASE openai_client AS PERM = <8000000 * number of AMPs>;
DATABASE openai_client;
GRANT CREATE EXTERNAL PROCEDURE ON openai_client TO dbc;
GRANT CREATE FUNCTION ON openai_client TO dbc;

2. Install the JAR:

CALL SQLJ.INSTALL_JAR(
  'cj!<path to openai.client-1.1.1.jar on a client machine including file name>',
  'OPENAI_CLIENT',
  0
);

3. Create/replace the functions:

REPLACE FUNCTION openai_client.CompleteChat()
RETURNS TABLE VARYING USING FUNCTION OpenAIClientTO_contract
LANGUAGE JAVA
NO SQL
PARAMETER STYLE SQLTable
EXTERNAL NAME 'OPENAI_CLIENT:com.teradata.openai.client.ChatCompletionTO.execute()';

REPLACE FUNCTION openai_client.Embeddings()
RETURNS TABLE VARYING USING FUNCTION EmbeddingsTO_contract
LANGUAGE JAVA
NO SQL
PARAMETER STYLE SQLTable
EXTERNAL NAME 'OPENAI_CLIENT:com.teradata.openai.client.EmbeddingsTO.execute()';       

4. Grant execution rights:

GRANT EXECUTE FUNCTION ON openai_client TO <desired_user>;

Notes

• TLS certificates: Provide via the optional cert input table if your server requires a custom CA. Cannot be used with IgnoreHTTPSVerification=True.
• Rate limiting: Retries are handled using Delays and RetriesNumber. Diagnostics are available with OutputProcessingDetails.
• DeepSeek: Use RemoveDeepSeekThinking('True') to strip <think> blocks.
• Embeddings length: EmbeddingLength must match your planned output size; the client enforces that the API returns at least that many values.
• Output choice for embeddings:
  • COLUMNAR: best for SQL analytics, direct filtering/aggregation.
  • BLOB/VARBYTE: compact binary storage (float32) in a single column named embeddings; ideal for storage or external tooling.