Guides

Catalog connector

The catalog connector queries data from CSV catalogs and supports geospatial proximity searches. Catalogs are scoped per agent, and each agent manages its own set of named catalogs.

Beta: The Catalog Connector is currently in beta. To upload a catalog, contact support.

Operations

queryData

Returns all rows from a catalog matching the specified criteria. If no criteria are provided, all rows are returned.

Criteria matching uses strict equality (===) and requires all specified key-value pairs to match (AND logic).

Parameters

ParameterTypeRequiredDefaultDescription
catalogIdstringYes—Name of the catalog to query
criteriaobjectNo{}Key-value pairs for exact-match filtering

Examples

Query with criteria:

// Input
{
  "catalogId": "products",
  "criteria": {
    "category": "electronics",
    "inStock": "true"
  }
}

// Output
{
  "result": [
    { "id": "101", "name": "Wireless Headphones", "category": "electronics", "inStock": "true", "price": "49.99" },
    { "id": "104", "name": "Bluetooth Speaker", "category": "electronics", "inStock": "true", "price": "29.99" }
  ]
}

Query without criteria (return all rows):

// Input
{
  "catalogId": "products"
}

// Output
{
  "result": [
    { "id": "101", "name": "Wireless Headphones", "category": "electronics", "inStock": "true", "price": "49.99" },
    { "id": "102", "name": "Running Shoes", "category": "footwear", "inStock": "false", "price": "89.99" },
    { "id": "103", "name": "Coffee Maker", "category": "appliances", "inStock": "true", "price": "39.99" }
  ]
}

Query using template variables:

{
  "catalogId": "{{ params.catalogId }}",
  "criteria": {{ params.filters | json }}
}

findNearest

Returns the nearest entries from a location catalog to a given coordinate, sorted by distance (closest first). Distance is calculated using the Haversine formula and expressed in meters.

Parameters

ParameterTypeRequiredDefaultDescription
catalogIdstringYes—Name of the location catalog to query
latitudenumberYes—Query latitude in decimal degrees
longitudenumberYes—Query longitude in decimal degrees
limitnumberNo10Maximum number of results to return

Response Shape

Results match the SearchForTextResult shape from @aws-sdk/client-location, extended with an optional Place.Phone field.

Note: Place.Geometry.Point follows the AWS convention of [longitude, latitude] order.

[
  {
    "Distance": 1240.5,
    "Place": {
      "Geometry": { "Point": [-118.2437, 34.0522] },
      "Label": "Downtown Branch, 123 Main St, Los Angeles, CA 90012",
      "Street": "123 Main St",
      "Municipality": "Los Angeles",
      "Region": "CA",
      "PostalCode": "90012",
      "Phone": "213-555-0100"
    }
  }
]

Examples

Find nearest 3 locations:

// Input
{
  "catalogId": "store-locations",
  "latitude": 34.0522,
  "longitude": -118.2437,
  "limit": 3
}

// Output
{
  "result": [
    {
      "Distance": 1240.5,
      "Place": {
        "Geometry": { "Point": [-118.2437, 34.0522] },
        "Label": "Downtown Branch, 123 Main St, Los Angeles, CA 90012",
        "Street": "123 Main St",
        "Municipality": "Los Angeles",
        "Region": "CA",
        "PostalCode": "90012",
        "Phone": "213-555-0100"
      }
    },
    {
      "Distance": 3870.2,
      "Place": {
        "Geometry": { "Point": [-118.2673, 34.0736] },
        "Label": "Westside Branch, 456 Elm Ave, Los Angeles, CA 90026",
        "Street": "456 Elm Ave",
        "Municipality": "Los Angeles",
        "Region": "CA",
        "PostalCode": "90026",
        "Phone": "213-555-0200"
      }
    }
  ]
}

Find nearest using template variables:

{
  "catalogId": "store-locations",
  "latitude": {{ message.location.latitude }},
  "longitude": {{ message.location.longitude }},
  "limit": {{ params.maxResults }}
}

CSV Format

Catalog CSVs must use a header row. Column names are case-sensitive.

queryData catalogs

Any column structure is supported. All columns are returned as string values.

id,name,category,inStock,price
101,Wireless Headphones,electronics,true,49.99
102,Running Shoes,footwear,false,89.99
103,Coffee Maker,appliances,true,39.99

findNearest catalogs

The following columns are required:

ColumnDescription
latitudeLatitude in decimal degrees
longitudeLongitude in decimal degrees
nameLocation name
addressStreet address
cityCity
stateState or region abbreviation
zipPostal code

The following column is optional:

ColumnDescription
phonePhone number (included in Place.Phone if present)
name,address,city,state,zip,phone,latitude,longitude
Downtown Branch,123 Main St,Los Angeles,CA,90012,213-555-0100,34.0522,-118.2437
Westside Branch,456 Elm Ave,Los Angeles,CA,90026,213-555-0200,34.0736,-118.2673

Using template variables

When using template variables with LiquidJS templates, objects and arrays require special handling.

⚠️

Important: Do not wrap object or array variables in quotes. Use the | json filter to properly serialize them.

Variable TypeSyntaxExample
String"{{ variable }}""catalogId": "{{ params.catalog }}"
Object/Array{{ variable | json }}"criteria": {{ params.filters | json }}
Number{{ variable }}"limit": {{ params.maxResults }}
Boolean{{ variable }}—

Updated 29 days ago