Querying Structured Data with the inmydata Agent API

Modified on Tue, 15 Jul at 2:25 PM

This article walks you through querying structured data from inmydata using the StructuredDataDriver. Structured data queries are extremely fast, making them ideal for building tools that power conversational interfaces—especially when you need to quickly retrieve data from the inmydata platform in real time.

You'll learn how to:

Connect using your tenant
Use a simple filter for basic equality queries
Use a complex filter with logical operators and brackets for more advanced conditions

Before starting, make sure you have:

Set up your environment variables (INMYDATA_API_KEY, INMYDATA_TENANT, INMYDATA_CALENDAR)
Installed the inmydata Python package and python-dotenv via pip

1. Load Environment Variables

Start by loading your credentials from the .env file:

import os
from dotenv import load_dotenv load_dotenv()

2. Initialize the Structured Data Driver

Create an instance of the StructuredDataDriver using your tenant:

from inmydata.StructuredData import StructuredDataDriver
driver = StructuredDataDriver(os.environ['INMYDATA_TENANT'])

3. Use `get_data_simple()` for Basic Filtering

Use get_data_simple() when your filters are simple equality filters with no brackets or OR logic.

Example: Filter sales data for the Edinburgh store

import os
from dotenv import load_dotenv
from inmydata.StructuredData import (
    StructuredDataDriver, 
    AIDataSimpleFilter,
    TopNOption
)

load_dotenv()

driver = StructuredDataDriver(os.environ['INMYDATA_TENANT'])

# -- Use get_data_simple when your filter is simple (only equality filters, no bracketing, no ORs, etc.)

# Build our simple filter
filter = []
filter.append(
    AIDataSimpleFilter(
        "Store", # Field to filter on
        "Edinburgh") # Value to filter by
    ) 

# Build a TopN filter to only show the Top 10 Sales People based on Sales Value
TopN = TopNOption("Sales Value", 10) # Field to order by and number of records to return (Positive for TopN, negative for BottomN)
TopNOptions = {}
TopNOptions["Sales Person"] = TopN # Apply the Top N option to the Sales Person field

df = driver.get_data_simple(
    "Inmystore Sales", # Name of the subject we want to extract data from
    ["Sales Person","Sales Value"], # List of fields we want to extract
    filter, # Filters to apply
    False, # Whether filters are case sensitive
    TopNOptions) # Apply the Top 10 Sales People based on Sales Value filter

print(df)

4. Use `get_data()` for Complex Filtering

Use get_data() when your filter requires:

Multiple conditions
Logical operators like AND/OR
Bracketing for precedence
Non-equality comparisons

In this example, we build a filter to match records where the Store is either Edinburgh or London. This uses the AIDataFilter class and logical operators to combine conditions.

import os
from dotenv import load_dotenv
from inmydata.StructuredData import (
    StructuredDataDriver,
    AIDataFilter, 
    LogicalOperator, 
    ConditionOperator
)

load_dotenv()

driver = StructuredDataDriver(os.environ['INMYDATA_TENANT'])

# -- Use get_data when your filter more complex (non-equality matches, bracketing, ORs, etc.) --

# Build our filter
filter = [] 
filter.append(
    AIDataFilter(
        "Store",
        ConditionOperator.Equals, # Condition to use in the filter
        LogicalOperator.And, # Logical operator to use in the filter
        "Edinburgh", # Value to filter by
        0, # Number of brackets before this condition
        0, # Number of brackets after this condition
        False # Whether the filter is case sensitive
    )
)
filter.append(
    AIDataFilter(
        "Store",
        ConditionOperator.Equals, # Condition to use in the filter
        LogicalOperator.Or, # Logical operator to use in the filter
        "London", # Value to filter by
        0, # Number of brackets before this condition
        0, # Number of brackets after this condition
        False # Whether the filter is case sensitive
    )
)
df = driver.get_data(
    "Inmystore Sales", # Name of the subject we want to extract data from
    ["Financial Year","Store","Sales Value"], # List of fields we want to extract
    filter, # Filters to apply
    {}) # Apply no TopN options

print(df)

5. Use `get_chart()` to generate a chart

Use get_chart() to generate a chart. Charts are rendered using the inmydata Agentic Chart web component, see Displaying charts generated by Agentic AI workflows. You must specify a valid user for the inmydata platform by setting the user property on the data component in your agent. The event raised by the inmydata platform to trigger the display of the chart will only be raised for that user.

In this example, we generate a chart to show the top 10 sales people in the Edinburgh store based on value sold in 2025.

import os
from dotenv import load_dotenv
from inmydata.StructuredData import (
    StructuredDataDriver,
    AIDataFilter, 
    LogicalOperator, 
    ConditionOperator, 
    TopNOption, 
    ChartType
)

load_dotenv()

driver = StructuredDataDriver(os.environ['INMYDATA_TENANT'])
driver.user = "demo" # Events to display charts will be available to the user specified here
driver.session_id = "test-session" # Session ID passed in the event to display charts. Can optionally be used to only show charts for the current session

# -- Use get_chart to generate a chart based on the data -- see https://developer.inmydata.com/support/solutions/articles/36000577995-displaying-charts-generated-by-agentic-ai-workflows

# Build our filter
filter = [] 
filter.append(
    AIDataFilter(
        "Store",
        ConditionOperator.Equals, # Condition to use in the filter
        LogicalOperator.And, # Logical operator to use in the filter
        "Edinburgh", # Value to filter by
        0, # Number of brackets before this condition
        0, # Number of brackets after this condition
        False # Whether the filter is case sensitive
    )
)
filter.append(
    AIDataFilter(
        "Financial Year",
        ConditionOperator.Equals, # Condition to use in the filter
        LogicalOperator.And, # Logical operator to use in the filter
        "2025", # Value to filter by
        0, # Number of brackets before this condition
        0, # Number of brackets after this condition
        False # Whether the filter is case sensitive
    )
)

# Build a TopN filter to only show the Top 10 Sales People based on Sales Value
TopN = TopNOption("Sales Value", 10) # Field to order by and number of records to return (Positive for TopN, negative for BottomN)
TopNOptions = {}
TopNOptions["Sales Person"] = TopN # Apply the Top N option to the Sales Person field

chartId = driver.get_chart(
    "Inmystore Sales", # Name of the subject we want to extract data from
    ["Sales Person"], # Chart row fields
    [], # Chart Column Fields
    ["Sales Value"], # Chart value fields
    filter, # Filters to apply
    ChartType.Bar, # Type of chart to generate
    "Top 10 Sales People in Edinburgh for 2025", # Title of the chart
    TopNOptions, # Apply the Top 10 Sales People based on Sales Value filter
)

Notes

Both get_data_simple() and get_data() return a Pandas DataFrame.
Use get_data_simple() when possible — it's more readable and easier to construct.
Brackets and logical operators in AIDataFilter allow for flexible nesting of conditions.
get_chart returns the ID of the generated chart. Charts should be rendered using the inmydata Agentic Chart web component, see Displaying charts generated by Agentic AI workflows.