AI_EXTRACT¶

Syntax¶

Extract information from an input string:

AI_EXTRACT( <text>, <responseFormat> )

AI_EXTRACT( text => <text>,
            responseFormat => <responseFormat>,
            [ scores => TRUE | FALSE ] )

Extract information from a file:

AI_EXTRACT( <file>, <responseFormat> )

AI_EXTRACT( file => <file>,
            responseFormat => <responseFormat>,
            [ config => <config_object> ],
            [ scores => TRUE | FALSE ] )

Arguments¶

text

An input string for extraction.

file

A FILE for extraction.

Supported file formats:

• PDF

• PNG

• PPTX, PPT

• EML

• DOC, DOCX

• JPEG, JPG

• HTM, HTML

• TEXT, TXT

• TIF, TIFF

• BMP, GIF, WEBP

• MD

The files must be less than 100 MB in size.

responseFormat

Information to be extracted. The format depends on the type of extraction.

Entity extraction formats

Extract single values by providing one of the following formats:

• Simple object schema that maps the label and information to be extracted:

  Expand

  {'name': 'What is the last name of the employee?', 'address': 'What is the address of the employee?'}
  

  Show lessSee more

  Scroll to top

• An array of strings that contain the information to be extracted:

  Expand

  ['What is the last name of the employee?', 'What is the address of the employee?']
  

  Show lessSee more

  Scroll to top

• An array of arrays that contain two strings (label and the information to be extracted):

  Expand

  [['name', 'What is the last name of the employee?'], ['address', 'What is the address of the employee?']]
  

  Show lessSee more

  Scroll to top

• A JSON schema with 'type': 'string' on the sub-object:

  Expand

  {
    'schema': {
      'type': 'object',
      'properties': {
        'title': {
          'description': 'What is the title of the document?',
          'type': 'string'
        }
      }
    }
  }
  

  Show lessSee more

  Scroll to top

List extraction format

Extract arrays of values using a JSON schema with 'type': 'array' on the sub-object:

Expand

{
  'schema': {
    'type': 'object',
    'properties': {
      'employees': {
        'description': 'What are the names of employees?',
        'type': 'array'
      }
    }
  }
}

Show lessSee more

Scroll to top

Table extraction format

Extract tabular data using a JSON schema with 'type': 'object' and column_ordering. Each column is defined as a nested property with 'type': 'array' and a description that matches the column name in the file:

Expand

{
  'schema': {
    'type': 'object',
    'properties': {
      'income_table': {
        'description': 'Income for FY2026Q2',
        'type': 'object',
        'column_ordering': ['month', 'income'],
        'properties': {
          'month': {
            'description': 'Month',
            'type': 'array'
          },
          'income': {
            'description': 'Income',
            'type': 'array'
          }
        }
      }
    }
  }
}

Show lessSee more

Scroll to top

Note

• You can’t combine the JSON schema format with other response formats. If responseFormat contains the schema key, you must define all questions within the JSON schema. Additional keys are not supported.

• The model only accepts certain shapes of JSON schema. Top level type must always be an object, which contains independently extracted sub-objects. Sub-objects may be a table (object of lists of strings representing columns), a list of strings, or a string.

  String is currently the only supported scalar type.

• Use the description field to provide context to the model; for example, to help the model localize the right table in a document. You can enter the column header name, or describe the column in other way.

• Use the column_ordering field to specify the order of all columns in the extracted table. The column_ordering field is case-sensitive and must match the column names defined in the properties field. The order should reflect the order of the columns in the document.

scores => boolean

Optional. Supported only in the named-argument syntax shown above. A BOOLEAN that controls whether the function returns scores for extracted values. The default is FALSE. When TRUE, the JSON result includes a scoring object in addition to response. For the output format, SQL examples, and limitations, see Extraction scores (preview).

config => config_object

An OBJECT value that specifies the configuration settings. You can use an OBJECT constant to specify this object.

You can specify the following key-value pairs in this object:

Key

Description

scale_factor

A numeric value from 1.0 through 4.0. Scales pages of an input file before they are processed by the underlying model, which can enhance OCR quality and improve extraction results. Use scale_factor if you receive unexpected or unclear responses in the following scenarios: Documents with page sizes larger than A4 Documents containing small text, detailed visual elements, or dense layouts Extracted text contains typos or character-level OCR errors If omitted, AI_EXTRACT uses the default value ('scale_factor': 1.0).

See moreShow less

Expand

Returns¶

A JSON object containing the extracted information. The structure of the response depends on the type of extraction.

{
  "error": null,
  "response": {
    "title": "Financial report"
  }
}

{
  "error": null,
  "response": {
    "employees": [
      "Smith",
      "Johnson",
      "Doe"
    ]
  }
}

{
  "error": null,
  "response": {
    "income_table": {
      "income": ["$120 678","$130 123","$150 998"],
      "month": ["February", "March", "April"]
    }
  }
}

{
  "error": null,
  "response": {
    "employees": [
      "Smith",
      "Johnson",
      "Doe"
    ],
    "income_table": {
      "income": ["$120 678","$130 123","$150 998"],
      "month": ["February", "March", "April"]
    },
    "title": "Financial report"
  }
}

Extraction scores (preview)¶

When you use AI_EXTRACT, you can request scores that indicate the model’s certainty about each extracted value. You can use these scores to set thresholds for business logic, such as flagging low-scoring extractions for human review.

A higher score indicates a higher likelihood that the extracted value is correct. You can compare scores for extracting a given entity across different documents to identify which values are more or less reliable, and use them to build deterministic processing logic such as thresholds, fallback mechanisms, and human-in-the-loop workflows.

{
  "response": {
    "name": "John Smith",
    "address": "123 Main St, San Francisco"
  },
  "scoring": {
    "scores": {
      "name": {
        "score": 0.95
      },
      "address": {
        "score": 0.82
      }
    }
  },
  "error": null
}

{
  "response": {
    "employees": ["Smith", "Johnson", "Doe"]
  },
  "scoring": {
    "scores": {
      "employees": {
        "score": 0.77
      }
    }
  },
  "error": null
}

{
  "response": {
    "income_table": {
      "month": ["February", "March", "April"],
      "income": ["$120 678", "$130 123", "$150 998"]
    }
  },
  "scoring": {
    "scores": {
      "income_table": {
        "score": 0.85
      }
    }
  },
  "error": null
}

SELECT AI_EXTRACT(
  file => TO_FILE('@db.schema.files', 'document.pdf'),
  responseFormat => {'name': 'What is the last name of the employee?', 'date': 'What is the inspection date?'},
  scores => TRUE
);

{
  "response": {
    "date": "2022-04-01",
    "name": "Johnson"
  },
  "scoring": {
    "scores": {
      "date": {
        "score": 0.96
      },
      "name": {
        "score": 0.99
      }
    }
  },
  "error": null
}

SELECT AI_EXTRACT(
  file => TO_FILE('@db.schema.files', 'agreement.pdf'),
  responseFormat => {
    'schema': {
      'type': 'object',
      'properties': {
        'buyer_list': {
          'description': 'What are the buyer names?',
          'type': 'array'
        }
      }
    }
  },
  scores => TRUE
);

{
  "response": {
    "buyer_list": [
      "John Davis",
      "Jane Davis"
    ]
  },
  "scoring": {
    "scores": {
      "buyer_list": {
        "score": 0.91
      }
    }
  },
  "error": null
}

SELECT AI_EXTRACT(
  file => TO_FILE('@db.schema.files', 'report.pdf'),
  responseFormat => {
    'schema': {
      'type': 'object',
      'properties': {
        'income_table': {
          'description': 'Income for FY2026Q2',
          'type': 'object',
          'column_ordering': ['month', 'income'],
          'properties': {
            'month': {
              'description': 'Month',
              'type': 'array'
            },
            'income': {
              'description': 'Income',
              'type': 'array'
            }
          }
        }
      }
    }
  },
  scores => TRUE
);

{
  "response": {
    "income_table": {
      "income": ["$120 678", "$130 123", "$150 998"],
      "month": ["February", "March", "April"]
    }
  },
  "scoring": {
    "scores": {
      "income_table": {
        "score": 0.88
      }
    }
  },
  "error": null
}

Access control requirements¶

Users must use a role that has been granted the SNOWFLAKE.CORTEX_USER database role. For information about granting this privilege, see Cortex LLM privileges.

Usage notes¶

• AI_EXTRACT is optimized for documents both digital-born and scanned.

• You can’t use both text and file parameters simultaneously in the same function call.

• You can either ask questions in natural language or describe information to be extracted (such as city, street, ZIP code); for example:

  Expand

  {'address': 'City, street, ZIP', 'name': 'First and last name'}
  

  Show lessSee more

  Scroll to top

• The following languages are supported:

  • Arabic

  • Bengali

  • Burmese

  • Cebuano

  • Chinese

  • Czech

  • Dutch

  • English

  • French

  • German

  • Hebrew

  • Hindi

  • Indonesian

  • Italian

  • Japanese

  • Khmer

  • Korean

  • Lao

  • Malay

  • Persian

  • Polish

  • Portuguese

  • Russian

  • Spanish

  • Tagalog

  • Thai

  • Turkish

  • Urdu

  • Vietnamese

• The documents must be no more than 125 pages long.

• In a single AI_EXTRACT call, you can ask a maximum of 100 questions for entity extraction, and a maximum of 10 questions for table extraction.

  A table extraction question is equal to 10 entity extraction questions. For example, you can ask 4 table extraction questions and 60 entity extraction questions in a single AI_EXTRACT call.

• The maximum output length for entity extraction is 512 tokens per question. For table extraction, the model returns answers that are a maximum of 4096 tokens.

• Client-side encrypted stages are not supported.

• Optional extraction scores are available in preview when you use named arguments and pass scores => TRUE. For details, see Extraction scores (preview).

Cost considerations¶

• The Cortex AI_EXTRACT function incurs compute cost based on the number of pages per document, input prompt tokens, and output tokens processed.

  • For paged file formats (PDF, DOCX, TIF, TIFF), each page is counted as 970 tokens.

  • For image file formats (JPEG, JPG, PNG), each individual image file is billed as a page and counted as 970 tokens.

• Using the scale_factor parameter changes how many tokens are consumed and how many pages can be processed per call:

  • The number of input tokens consumed increases proportionally with scale_factor.

  • The maximum number of pages per document that can be processed by AI_EXTRACT decreases by scale_factor.

  Relationship of scale_factor to number of tokens and pages

  scale_factor value	Token count per page	Max. number of pages per document
  2	970 * 2 = 1940 tokens	125/2 = 62.5 (rounded down to 62)
  2.5	970 * 2.5 = 2425 tokens	125/2.5 = 50
  4	970 * 4 = 3880 tokens	125/4 = 31.25 (rounded down to 31)

  See moreShow less

  Expand

• Snowflake recommends executing queries that call the Cortex AI_EXTRACT function in a smaller warehouse (no larger than MEDIUM). Larger warehouses don’t increase performance.

Regional availability¶

AI_EXTRACT is available to accounts in the following regions:

AI_EXTRACT has cross-region support. For information on enabling Cortex AI cross-region support, see Cross-region inference.

Error conditions¶

AI_EXTRACT can produce the following error messages:

Examples¶

SELECT AI_EXTRACT(
  file => TO_FILE('@db.schema.files', 'report.pdf'),
  responseFormat => {
    'schema': {
      'type': 'object',
      'properties': {
        'employees': {
          'description': 'What are the surnames of employees?',
          'type': 'array'
        }
      }
    }
  }
);

SELECT AI_EXTRACT(
  file => TO_FILE('@db.schema.files', 'report.pdf'),
  responseFormat => {
    'schema': {
      'type': 'object',
      'properties': {
        'income_table': {
          'description': 'Income for FY2026Q2',
          'type': 'object',
          'column_ordering': ['month', 'income'],
          'properties': {
            'month': {
              'description': 'Month',
              'type': 'array'
            },
            'income': {
              'description': 'Income',
              'type': 'array'
            }
          }
        }
      }
    }
  }
);

SELECT AI_EXTRACT(
  file => TO_FILE('@db.schema.files', 'report.pdf'),
  responseFormat => {
    'schema': {
      'type': 'object',
      'properties': {
        'income_table': {
          'description': 'Income for FY2026Q2',
          'type': 'object',
          'column_ordering': ['month', 'income'],
          'properties': {
            'month': {
              'description': 'Month',
              'type': 'array'
            },
            'income': {
              'description': 'Income',
              'type': 'array'
            }
          }
        },
        'title': {
          'description': 'What is the title of document?',
          'type': 'string'
        },
        'employees': {
          'description': 'What are the surnames of employees?',
          'type': 'array'
        }
      }
    }
  }
);

SELECT AI_EXTRACT(
  file => TO_FILE('@db.schema.files', 'report.pdf'),
  responseFormat => {
    'schema': {
      'type': 'object',
      'properties': {
        'employees': {
          'description': 'What are the surnames of employees?',
          'type': 'array'
        }
      }
    }
  },
  config => {'scale_factor': 2.0}
);

SELECT AI_EXTRACT(
  model => 'db.schema.my_tuned_model',
  file => TO_FILE('@db.schema.files','document.pdf')
);

SELECT AI_EXTRACT(
  model => 'db.schema.my_tuned_model',
  file => TO_FILE('@db.schema.files','document.pdf'),
  responseFormat => [['name', 'What is the first name of the employee?'], ['city', 'Where does the employee live?']]
);

SELECT AI_EXTRACT(
  model => 'db.schema.my_tuned_model',
  file => TO_FILE('@db.schema.files', 'invoice.pdf'),
  config => {'scale_factor': 2.0}
);

Legal notices¶

Refer to Snowflake AI and ML for legal notices.