Cloudera Docs

Overview of AI function syntax and arguments

Learn how you can use the ai_generate_text functions to connect to AI endpoints and integrate AI models into your Impala SQL queries.

Syntax for AI built-in function arguments

The following example of a built-in AI function demonstrates the use of the OpenAI API as a large language model. Currently, OpenAI's public endpoint and Azure OpenAI endpoints are supported.

AI_GENERATE_TEXT_DEFAULT
Syntax
ai_generate_text_default(prompt)
AI_GENERATE_TEXT
Syntax
ai_generate_text(ai_endpoint, prompt, ai_model, auth_credential, platform_params, impala_options)

The ai_generate_text function uses the values you provide as an argument in the function for ai_ endpoint, ai_model, and auth_credential. If any of them are left empty or NULL, the function uses the default values set at the instance level instead.

When using the ai_generate_text_default function, make sure to set all parameters (ai_ endpoint, ai_model, and ai_api_key_jceks_secret) in the coordinator/executor flagfiles with appropriate values.

Key parameters for using the AI model

In Impala's AI functions, parameters can come from either:
  • Function arguments (when calling ai_generate_text or ai_generate_text_default).
  • Startup flags (set when starting the Impala daemon).

Parameters can be set via function arguments or instance level startup flags. If both are provided, the argument overrides the flag for that request. Parameter Reference:

  • ai_endpoint (Argument & Flag): The endpoint for the model API that is being interfaced with, supports services like OpenAI and Azure OpenAI Service, for example, https://api.openai.com/v1/chat/completions. For other AI platforms, you must specify the platform name through the ai_api_additional_platforms flag
  • prompt (Argument only): The text you submit to the AI model to generate a response.
  • ai_model: The specific model name you want to use within the desired API, for example, gpt-3.5-turbo.
  • auth_credential (Argument only): The authentication credential can either be a JCEKS API key secret or plain text, depending on the credential_type specified in the impala_options. By default, "jceks" is selected, and this parameter is the key name for the JCEKS secret that contains your API key for the AI API you are using. You need a JCEKS keystore containing the specified JCEKS secret referenced in the argument auth_credential or the flag ai_api_key_jceks_secret. To configure the keystore file location, see Configuring the JCEKS keystore for Impala AI integration. If "plain_text" is selected, this parameter should contain the plain text token instead.
  • ai_api_key_jceks_secret (Flag only): The key name for the JCEKS secret that contains your API key for the AI API you are using. You need a JCEKS keystore containing the specified JCEKS secret referenced in the argument auth_credential or the flag ai_api_key_jceks_secret.To configure the keystore file location, see Configuring the JCEKS keystore for Impala AI integration.
  • platform_params (Argument only): Additional parameters that the AI API offers that is provided to the built-in function as a JSON object
  • impala_options (Argument only): Additional options in the form of a JSON object that Impala accepts for constructing the request.
    • api_standard: "openai" is the only option by default.
    • credential_type: Choose the credential type. The selectable values are "plain or "jceks", with "jceks" as the default. If "jceks" is chosen, Impala will treat the provided credential token as a JCEKS token. If "plain" is selected, Impala will treat the provided credential token as plain text.
    • payload: A customized payload. If provided, the request will use this payload directly.
  • ai_api_additional_platforms (Flag only): A string-formatted list of additional AI platforms, separated by commas (e.g., "a.com,b.com,c.com"). See Configuring for other AI platforms.