Query Products

the query endpoints let you search and filter product docid 77yxhqwwag2 bxxtxuziu across models using a json style query language you can filter by ifc docid\ st7bomqta9pkl5acrtcu5 , property values, quantities, and more each query returns a list of product docid 77yxhqwwag2 bxxtxuziu objects filtering by model and revision all query endpoints share the same filtering logic for models and revisions, controlled through the model and revision parameters both accept multiple values and are resolved in order if model is specified, the query targets the latest revision of each given model if only revision is specified, the query targets those exact revisions if neither is specified, the query targets the latest revision of every model in the project all endpoints accept model and revision as repeatable query parameters (e g ?model=id1\&model=id2 ) post endpoints also accept models and revisions arrays (note the plural form) in the request body when both are present, the body value takes precedence list product fields list the fields that can be queried for products get /v2/projects/{project id}/ifc/products/fields query parameters name type description data mode string explicit (default) returns fields as stored inferred merges type properties with product properties model string filter by model id revision string filter by revision id page number page number (default 1 ) pagesize number results per page (default 1000 ) example curl x get \\ "https //api catenda com/v2/projects/{project id}/ifc/products/fields" \\ \ header "authorization bearer $access token" \\ \ header 'accept application/json' response \[ { "field" "attributes globalid", "type" "string", "measuretype" null }, { "field" "attributes name", "type" "string", "measuretype" null }, { "field" "ifctype", "type" "string", "measuretype" null }, { "field" "objectid", "type" "number", "measuretype" null }, { "field" "quantitysets basequantities quantities width", "type" "number", "measuretype" "length" }, { "field" "propertysets pset wallcommon properties isexternal", "type" "boolean", "measuretype" null } ] the measuretype field indicates the physical measure type of a field common values include "length" , "area" , and null for non measure fields field names map directly to the product docid 77yxhqwwag2 bxxtxuziu json structure for example, propertysets pset wallcommon properties isexternal corresponds to the isexternal property inside the pset wallcommon property set a post variant of this endpoint is also available it accepts the same query parameters and an optional request body with models and revisions arrays query suggested field values query suggested values for a specific field this is useful for building autocomplete interfaces or discovering available values post /v2/projects/{project id}/ifc/products/fields/suggested values query parameters name type description data mode string explicit (default) returns fields as stored inferred merges type properties with product properties model string filter by model id revision string filter by revision id request body name type description field string the field to get values for (required) search string search term to filter values, or an empty string to return the most common values (required) models array filter by model ids revisions array filter by revision ids example curl x post \\ "https //api catenda com/v2/projects/{project id}/ifc/products/fields/suggested values" \\ \ header "authorization bearer $access token" \\ \ header 'accept application/json' \\ \ header 'content type application/json' \\ \ data raw '{ "field" "ifctype", "search" "wall" }' response \[ { "value" "ifcwall" }, { "value" "ifcwallstandardcase" } ] query products query products using a json style query language based on the mongodb query language https //docs mongodb com/manual/reference/operator/query/ post /v2/projects/{project id}/ifc/products query parameters name type description data mode string explicit (default) returns fields as stored inferred merges type properties with product properties model string filter by model id revision string filter by revision id page number page number (default 1 ) pagesize number results per page (default 100 , max 1000 ) request body name type description query object query expression (required) fields object field projection — use 1 to include specific fields or 0 to exclude them models array filter by model ids revisions array filter by revision ids filter by model or revision when possible to reduce query scope and improve performance example curl x post \\ "https //api catenda com/v2/projects/{project id}/ifc/products" \\ \ header "authorization bearer $access token" \\ \ header 'accept application/json' \\ \ header 'content type application/json' \\ \ data raw '{ "query" { "ifctype" { "$eq" "ifcwall" } }, "fields" { "attributes name" 1, "ifctype" 1 } }' response returns an array of product docid 77yxhqwwag2 bxxtxuziu objects field projection the fields parameter controls which fields are returned for each product use dot notation to target nested fields if fields is omitted or empty, all fields are returned include specific fields only { "fields" { "attributes name" 1, "ifctype" 1 } } returns only the listed fields objectid is always included unless explicitly excluded with "objectid" 0 exclude specific fields { "fields" { "quantitysets" 0, "materials" 0 } } returns all fields except the listed ones you can mix 1 and 0 in a single projection fields are processed in the order given, so overlapping paths may produce different results depending on their sequence query language implicit equality a field mapped directly to a value implies $eq { "query" { "ifctype" "ifcwall" } } is equivalent to { "query" { "ifctype" { "$eq" "ifcwall" } } } comparison operators $eq — equal { "query" { "ifctype" { "$eq" "ifcwall" } } } $ne — not equal { "query" { "ifctype" { "$ne" "ifcspace" } } } $gt / $gte — greater than / greater than or equal { "query" { "quantitysets basequantities quantities width" { "$gt" 0 2 } } } { "query" { "quantitysets basequantities quantities width" { "$gte" 0 19 } } } $lt / $lte — less than / less than or equal { "query" { "quantitysets basequantities quantities height" { "$lt" 3 0 } } } { "query" { "quantitysets basequantities quantities height" { "$lte" 2 8 } } } set operators $in — match any value in array { "query" { "ifctype" { "$in" \["ifcwall", "ifcslab", "ifccolumn"] } } } $nin — match none of the values { "query" { "ifctype" { "$nin" \["ifcspace", "ifcopeningelement"] } } } logical operators $and — match all conditions { "query" { "$and" \[ { "ifctype" "ifcwall" }, { "attributes name" { "$regex" "exterior", "$options" "i" } } ] } } $or — match any condition { "query" { "$or" \[{ "ifctype" "ifcwall" }, { "ifctype" "ifcslab" }, { "ifctype" "ifccolumn" }] } } $not — negate a condition { "query" { "attributes name" { "$not" { "$regex" "internal", "$options" "i" } } } } string operators $regex — regular expression match { "query" { "attributes name" { "$regex" "wall" } } } use $options to set flags { "query" { "attributes name" { "$regex" "wall", "$options" "i" } } } common patterns pattern description "wall" contains "wall" "^basic wall" starts with "basic wall" "200mm$" ends with "200mm" available $options flags flag description i case insensitive matching m multi line ( ^ / $ match line boundaries) s dot matches newlines do not use regex syntax like "/pattern/i" the pattern and options are always separate fields existence operator $exists — check if field is present { "query" { "propertysets pset wallcommon properties firerating" { "$exists" true } } } { "query" { "propertysets pset wallcommon properties firerating" { "$exists" false } } } full text search $text / $search — search across all fields performs full text search across all indexed string fields results are ranked by relevance { "query" { "$text" { "$search" "concrete structural" } } } ifc specific operator $ifctype — match ifc type hierarchy matches the specified ifc type and all its subtypes { "query" { "ifctype" { "$ifctype" "ifcwall" } } } this matches ifcwall , ifcwallstandardcase , ifcwallelementedcase , etc in contrast, $eq matches only the exact type { "query" { "ifctype" { "$eq" "ifcwall" } } } $ifctype accepts a single string to match multiple ifc types, wrap them in $or { "query" { "$or" \[{ "ifctype" { "$ifctype" "ifcwall" } }, { "ifctype" { "$ifctype" "ifcslab" } }] } } range queries combine comparison operators on the same field to create range queries { "query" { "quantitysets basequantities quantities width" { "$gte" 0 15, "$lte" 0 25 } } } this is equivalent to using $and { "query" { "$and" \[ { "quantitysets basequantities quantities width" { "$gte" 0 15 } }, { "quantitysets basequantities quantities width" { "$lte" 0 25 } } ] } } examples the examples below combine multiple operators to cover common real world queries find exterior walls wider than 190mm curl x post \\ "https //api catenda com/v2/projects/{project id}/ifc/products?data mode=inferred" \\ \ header "authorization bearer $access token" \\ \ header 'accept application/json' \\ \ header 'content type application/json' \\ \ data raw '{ "query" { "$and" \[ { "ifctype" { "$ifctype" "ifcwall" } }, { "attributes name" { "$regex" "exterior", "$options" "i" } }, { "quantitysets basequantities quantities width" { "$gte" 0 19 } } ] } }' find elements with fire rating curl x post \\ "https //api catenda com/v2/projects/{project id}/ifc/products" \\ \ header "authorization bearer $access token" \\ \ header 'accept application/json' \\ \ header 'content type application/json' \\ \ data raw '{ "query" { "$and" \[ { "propertysets pset wallcommon properties firerating" { "$exists" true } }, { "propertysets pset wallcommon properties firerating" { "$ne" "" } } ] } }' full text search curl x post \\ "https //api catenda com/v2/projects/{project id}/ifc/products" \\ \ header "authorization bearer $access token" \\ \ header 'accept application/json' \\ \ header 'content type application/json' \\ \ data raw '{ "query" { "$text" { "$search" "concrete" } } }' complex nested query find walls (including subtypes) that are not named "internal", and are either wider than 200mm or marked as external curl x post \\ "https //api catenda com/v2/projects/{project id}/ifc/products?data mode=inferred" \\ \ header "authorization bearer $access token" \\ \ header 'accept application/json' \\ \ header 'content type application/json' \\ \ data raw '{ "query" { "$and" \[ { "$or" \[ { "ifctype" { "$ifctype" "ifcwall" } }, { "ifctype" { "$ifctype" "ifccurtainwall" } } ] }, { "attributes name" { "$not" { "$regex" "internal", "$options" "i" } } }, { "$or" \[ { "quantitysets basequantities quantities width" { "$gte" 0 2 } }, { "propertysets pset wallcommon properties isexternal" true } ] } ] } }' operator quick reference operator type example $eq comparison { "field" { "$eq" "value" } } $ne comparison { "field" { "$ne" "value" } } $gt comparison { "field" { "$gt" 10 } } $gte comparison { "field" { "$gte" 10 } } $lt comparison { "field" { "$lt" 10 } } $lte comparison { "field" { "$lte" 10 } } $in set { "field" { "$in" \["a", "b"] } } $nin set { "field" { "$nin" \["a", "b"] } } $and logical { "$and" \[ ] } $or logical { "$or" \[ ] } $not logical { "field" { "$not" { } } } $regex string { "field" { "$regex" "pattern" } } $options string { "field" { "$regex" " ", "$options" "i" } } $exists existence { "field" { "$exists" true } } $text search { "$text" { "$search" "terms" } } $ifctype ifc { "ifctype" { "$ifctype" "ifcwall" } }