Guides
Start typing to search…

Catalog Connector

The Catalog Connector reads CSV files from S3 to support data queries and geospatial proximity searches against account-specific data catalogs.

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


Using Context Variables

When using context 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": "{{ context.parameters.catalog }}"
Object/Array{{ variable | json }}"criteria": {{ context.parameters.filters | json }}
Number{{ variable }}"limit": {{ context.parameters.maxResults }}
Boolean{{ variable }}—

Operations

queryData

Reads a CSV catalog from S3 and returns all rows 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—Filename (without .csv) of the catalog in S3
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 context variables:

{
  "catalogId": "{{ context.parameters.catalogId }}",
  "criteria": {{ context.parameters.filters | json }}
}

findNearest

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

Parameters

ParameterTypeRequiredDefaultDescription
catalogIdstringYes—Filename (without .csv) of the location catalog
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 context variables:

{
  "catalogId": "store-locations",
  "latitude": {{ context.parameters.userLat }},
  "longitude": {{ context.parameters.userLng }},
  "limit": {{ context.parameters.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

Updated 17 days ago