CertSafari
    Snowflake SnowPro Specialty: Gen AI (GES-C02)· Lessons

    Domain 4 · Lesson 12/15

    AI_EXTRACT: responseFormat, scores and writing extraction questions

    Use document parsing functions.

    9 min read
    3.75% of exam
    2 sources
    Published 21 Oct 2026
    Docs as of 4 Oct 2026

    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'
    Array-of-arrays entity format. The label is only the response key, so 'address' here holds an expiration datesql
    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.

    List extraction: a JSON schema with a type array sub-objectsql
    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': ' ? '
                }
            }
            }
        }
    );

    Checkpoint 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?

    Sources12

    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.

    Table extraction result: one array per column, not one object per rowjson
    {
      "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.

    Requesting scores with named argumentssql
    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?

    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 and the adjustment that addresses it
    SymptomAdjustment
    Answer picks the wrong one of several datesName the specific date in the question
    Values come from the wrong table on the pageAdd the table title or number to description
    Table extraction stops partway throughSplit by page or by column groups, then join the results
    Typos in extracted characters from small textRaise 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.

    Sources21

    Sources

    (2)

    Every claim above is drawn from one of these pages, quoted as it was written on the date shown.

    1. 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. 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

    Ready to test yourself?

    Practise the 13 questions on this subdomain.

    Spotted a mistake, or was something unclear? Tell us.