Skip to content

Multiple Queries

When you need to extract different types of information from the same data, structx provides the extract_queries method to process multiple queries efficiently.

Processing Flow

View Multiple Queries Processing Flow Diagram 
graph TD
    A[Input Data] --> B[Multiple Queries]
    B --> E[Sequential Extraction]

    E --> G1[Query 1]
    G1 --> G2[Query 2]
    G2 --> G3[Query 3]

    G3 --> H

    H --> I[Combined Results Map]

    subgraph "Per Query Process"
        J[Schema Generation] --> K[Model Creation]
        K --> L[Data Extraction]
        L --> M[Result Object]
    end

    G1 --> J

Basic Usage

# Define multiple queries for a legal document
queries = [
    "extract the parties involved, including their names and roles",
    "extract all important dates, such as effective date and termination date",
    "extract the payment terms, including amounts and schedules"
]

# Process all queries on the same document
results = extractor.extract_queries(
    data="scripts/example_input/free-consultancy-agreement.docx",
    queries=queries,
    return_df=False
)

# Access results by query
for query, result in results.items():
    print(f"\nResults for query: '{query}'")
    print(f"Processed {result.success_count} rows with {result.success_rate:.1f}% success rate")

    # Access the data
    for item in result.data:
        print(item.model_dump_json(indent=2))

    # Access the model
    print(f"Model used: {result.model.__name__}")

Return Format Options

Just like with single queries, you can control the return format:

# Return as DataFrames
results = extractor.extract_queries(
    data="scripts/example_input/S0305SampleInvoice.pdf",
    queries=["extract invoice number and total", "extract line items"],
    return_df=True
)

Async Processing

Use the async wrapper when calling from an async application:

import asyncio

async def process_queries():
    queries = [
        "extract client and consultant details",
        "summarize the scope of services"
    ]
    results = await extractor.extract_queries_async(
        data="scripts/example_input/free-consultancy-agreement.docx",
        queries=queries
    )
    return results

results = asyncio.run(process_queries())

Benefits of Multiple Queries

extract_queries provides a convenient result map for a list of queries:

  1. Organization: Results are keyed by the query that produced them.
  2. Consistency: Every query receives the same input value and options.
  3. Configuration: Return and file-reader options are applied consistently.
  4. Usage Tracking: Each returned result contains usage for that query.

The current implementation prepares the input and converts a document only once, then processes queries sequentially against that prepared data. Each query still receives its own model plan, result object, and usage tracker.

Use Cases

queries = [
    "extract all clauses related to intellectual property",
    "extract confidentiality obligations for both parties",
    "extract liability and indemnification clauses"
]

Different Levels of Detail from an Invoice

queries = [
    "extract high-level summary: invoice number, total amount, due date",
    "extract detailed line items with descriptions, quantities, and prices",
    "extract payment instructions and bank details"
]

Different Entity Types from a Contract

queries = [
    "extract information about all parties (names, addresses, roles)",
    "extract all defined terms and their definitions",
    "extract all monetary values and their context"
]

Next Steps