What you will be able to do
- Write a responseFormat that extracts entities, lists or tables from a file or a string
- Read AI_EXTRACT responses with and without confidence scores
- Write questions and table schemas that extract accurately, and handle long tables
1.Shaping the request with responseFormat
AI_EXTRACT pulls structured values out of a document. You ask it questions in natural language or describe the data you want. It runs on arctic-extract, a vision-based model, and it reads either a string (text =>) or a staged FILE (file =>) under 100 MB. The responseFormat argument decides what comes back: single values, lists or tables.
There are four ways to ask for single values (entities):
- A simple object that maps a label to a question, such as
{'name': 'What is the last name of the employee?'} - A plain array of question strings
- An array of two-element arrays, each holding a label and a question
- A JSON schema whose sub-object has
'type': 'string'
SELECT AI_EXTRACT(
file => TO_FILE('@db.schema.stage','document.pdf'),
responseFormat => [['seller_name', 'What is the seller name?'], ['address', 'What is the offer expiration date?']]
);Lists and tables can only be requested through the JSON schema format. A sub-object with 'type': 'array' returns a list, such as every buyer named on a contract. A sub-object with 'type': 'object' returns a table: each column is a nested property of type array, and column_ordering gives the column order. column_ordering is case-sensitive and must match the property names exactly.
SELECT AI_EXTRACT(
file => TO_FILE('@db.schema.files', 'report.pdf'),
responseFormat => {
'schema': {
'type': 'object',
'properties': {
'buyer_list': {
'description': 'What are the buyer names?',
'type': 'array'
}
}
}
}
);The schema accepts only a few shapes. The top level must be an object. Each sub-object inside it is extracted on its own and must be a string, a list of strings or a table. String is the only scalar type, so there is no number or date type. Once responseFormat contains a schema key, every question has to go inside that schema. You cannot put a simple label-to-question pair next to it. One schema can still ask for entities, lists and tables together, and they all come back in a single response.
Checkpoint 1 of 4· Fill the gap
This call should return every buyer named on the contract as a list. Which type value completes the schema?
SELECT AI_EXTRACT(
file => TO_FILE('@db.schema.files', 'report.pdf'),
responseFormat => {
'schema': {
'type': 'object',
'properties': {
'buyer_list': {
'description': 'What are the buyer names?',
'type': ' ? '
}
}
}
}
);To get a list back, the sub-object needs 'type': 'array'. 'string' returns a single value, and 'object' returns a table whose columns are nested array properties. 'list' is not a type the schema accepts.
Source: docs.snowflake.comCheckpoint 2 of 4· Check yourself
A developer's responseFormat has a 'schema' key that defines a line-items table. They want the invoice number too, so they add 'invoice_no': 'What is the invoice number?' next to 'schema' in the same object. What should they do?
Once responseFormat contains the schema key, every question must be defined inside that schema, and no extra keys are allowed. One schema can still ask for entities, lists and tables together, so a single call works as long as the invoice number is a string sub-object.
“If responseFormat contains the schema key, you must define all questions within the JSON schema. Additional keys are not supported.”Source: docs.snowflake.com
2.Reading the response and confidence scores
Every AI_EXTRACT result is a JSON object with an error field and a response field. The shape inside response mirrors what you asked for. An entity comes back as a key and a string. A list comes back as an array. A table comes back as an object of column arrays, so the first value of every column array together makes the first row.
{
"error": null,
"response": {
"income_table": {
"income": ["$120 678","$130 123","$150 998"],
"month": ["February", "March", "April"]
}
}
}Confidence scores are opt-in. With scores => TRUE, the result adds a scoring object next to response, holding one score between 0 and 1 for each extracted field. Higher means the value is more likely correct. Scores do not cost anything extra. They work only with named-argument syntax, so a positional call has no way to ask for them.
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
);Scores let you write fixed rules on top of the model. A typical one sends any invoice whose total scores below a threshold you choose to a human review queue and loads the rest directly. Scores for the same field are comparable across documents. A table is scored as a whole, though, so a low table score tells you to re-check the table without telling you which cell to look at.
Checkpoint 3 of 4· Check yourself
Which AI_EXTRACT call will return a scoring object, so that a pipeline can send invoices with a low-confidence total to human review?
Scores are off by default and only work with named-argument syntax as scores => TRUE. A positional TRUE cannot ask for them. Scores are a separate argument, not a key inside config.
“Use the optional scores argument in the named-argument syntax shown in Arguments.”Source: docs.snowflake.com
Sources1
3.Writing questions and table schemas that extract well
How accurate AI_EXTRACT is depends on how specific the question is. Ask in plain English, and know what answer you expect. Ask for one value per question. If a lease has both an issue date and a signature date, What is the date? leaves the model to choose. What is the signature date? does not. The model also knows nothing about your business: it will not guess what you meant or bring in specialist knowledge the document does not contain.
Table schemas follow the document, not your warehouse naming. Copy column names exactly as printed, so Report Date and not REPORT_DATE. Keep the document's casing, and list columns in the order they appear, usually left to right. Put columns whose value repeats across rows, such as Invoice Number, first. Avoid meaningless names like col1. The description field is usually optional. When a page has several similar tables and answers come from the wrong one, put the table title or number in description so the model finds the right table.
Long tables run into an output limit. Table answers stop at 4,096 tokens. A table that runs across several pages should be split into one-page documents, extracted page by page and joined afterwards. A single page too dense to finish should be split by columns, for example two schemas of five columns each for a ten-column table.
Blurry input is a separate problem with its own fix. For files, config => {'scale_factor': ...} scales pages by 1.0 to 4.0 before the model reads them, and the default is 1.0. Raise it for pages larger than A4, for small or dense text, or when extracted values contain character-level OCR typos.
| Symptom | Adjustment |
|---|---|
| Answer picks the wrong one of several dates | Name the specific date in the question |
| Values come from the wrong table on the page | Add the table title or number to description |
| Table extraction stops partway through | Split by page or by column groups, then join the results |
| Typos in extracted characters from small text | Raise scale_factor in config (1.0 to 4.0) |
Checkpoint 4 of 4· Match them up
Match each AI_EXTRACT problem to the change that fixes it.
Tap a term, then the definition that fits it.
The model does not guess which value you meant, so the question has to name it. The description field points the model to the right table. Table answers stop at 4,096 tokens, so long tables are split by page and joined afterwards. Scaling pages up with scale_factor fixes OCR typos from small text.
“If the answers come from a different source table than expected or the model can’t find the table, try using the description field.”Source: docs.snowflake.com
Sources
(2)
Every claim above is drawn from one of these pages, quoted as it was written on the date shown.
- 1.
“The files must be less than 100 MB in size.”
↩︎ Shaping the request with responseFormat“Top level type must always be an object, which contains independently extracted sub-objects.”
↩︎ Shaping the request with responseFormat“String is currently the only supported scalar type.”
↩︎ Shaping the request with responseFormat“The column_ordering field is case-sensitive and must match the column names defined in the properties field.”
↩︎ Shaping the request with responseFormat“Each field in scoring.scores corresponds to a field in response and contains a score value between 0 and 1.”
↩︎ Reading the response and confidence scores“Requesting scores does not incur additional cost.”
↩︎ Reading the response and confidence scores“such as flagging low-scoring extractions for human review.”
↩︎ Reading the response and confidence scores“Scales pages of an input file before they are processed by the underlying model, which can enhance OCR quality and improve extraction results.”
↩︎ Writing questions and table schemas that extract well“If responseFormat contains the schema key, you must define all questions within the JSON schema.”
↩︎ Exam trap 1“Supported only in the named-argument syntax shown above.”
↩︎ Exam trap 2“If responseFormat contains the schema key, you must define all questions within the JSON schema. Additional keys are not supported.”
↩︎ Checkpoint“Per-element scores for individual list items and table cells are not available.”
↩︎ Prediction“Use the optional scores argument in the named-argument syntax shown in Arguments.”
↩︎ Checkpoint - 2.
“AI_EXTRACT uses arctic-extract, a proprietary vision-based large language model (LLM)”
↩︎ Shaping the request with responseFormat“Ask for a single value in each question.”
↩︎ Writing questions and table schemas that extract well“Be specific; for example, if the document includes several dates (such as issuing date and signature date)”
↩︎ Writing questions and table schemas that extract well“To improve accuracy, define the columns in the same order as they appear in the document”
↩︎ Writing questions and table schemas that extract well“Add information that helps the model identify the right table, such as the table title or number.”
↩︎ Writing questions and table schemas that extract well“The model for table extraction returns answers that are up to 4096 tokens long.”
↩︎ Writing questions and table schemas that extract well“If the table covers several pages, split the document into multiple one-page documents, and join the results in postprocessing.”
↩︎ Writing questions and table schemas that extract well“Do not expect AI_EXTRACT to guess your intentions or have extended knowledge in a specific domain.”
↩︎ Exam trap 3“If the answers come from a different source table than expected or the model can’t find the table, try using the description field.”
↩︎ Checkpoint