> Portal Navigation: > > - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version. > - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages). > - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`). > - Top-level index of all portals: https://dev.wix.com/docs/llms.txt > - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt # QuerySemanticModelData # Package: analytics # Namespace: SemanticModelsService # Method link: https://dev.wix.com/docs/api-reference/business-management/analytics/semantic-models/query-semantic-model-data.md ## Permission Scopes: Site Analytics - read permissions: SCOPE.DC-ANALYTICS-AND-REPORTS.READ-SITE-ANALYTICS ## Introduction Retrieves data from a semantic model for the specified fields, filters, sorting, and paging. Query Semantic Model Data runs with these defaults, which you can override: - `paging.limit` is `50` - `paging.offset` is `0` To learn about working with Query methods, see [API Query Language](https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/data-retrieval/about-the-wix-api-query-language.md), [Sorting and Paging](https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/data-retrieval/about-sorting-and-paging.md), and [Field Projection](https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/data-retrieval/about-field-projection.md). --- ## REST API ### Schema ``` Method: querySemanticModelData Description: Retrieves data from a semantic model for the specified fields, filters, sorting, and paging. Query Semantic Model Data runs with these defaults, which you can override: - `paging.limit` is `50` - `paging.offset` is `0` To learn about working with Query methods, see [API Query Language](https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/data-retrieval/about-the-wix-api-query-language.md), [Sorting and Paging](https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/data-retrieval/about-sorting-and-paging.md), and [Field Projection](https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/data-retrieval/about-field-projection.md). URL: https://www.wixapis.com/analytics/semantic-model/v3/semantic-models/query-data Method: POST # Note: If the parameter `a.b` is listed under required parameters, `b` is only required if `a` is also present. Required parameters: semanticModelId, interval, fields Method parameters: param name: fields | type: array | description: List of field names to retrieve from the semantic model. Call `Get Semantic Model` to retrieve the semantic model's available fields. Fields with unmet dependencies (see the `dependencies` property in the semantic model schema) are silently omitted from results. | required: true | validation: maxItems 60, maxLength 5120 param name: filters | type: array | description: Filters to apply to the data query. Supported conditions: `EQUAL`, `GREATER_THAN`, `GREATER_THAN_OR_EQUAL`, `LESS_THAN`, `LESS_THAN_OR_EQUAL`, `NULL`, `EMPTY`, `START_WITH`, `END_WITH`, `CONTAINS_ANY`, `CONTAINS_ALL`, `RANGE_II` (inclusive start, inclusive end), `RANGE_IE` (inclusive start, exclusive end), `RANGE_EI` (exclusive start, inclusive end), and `RANGE_EE` (exclusive start, exclusive end). | validation: maxItems 60 - name: field | type: string | description: Name of the field to filter by. Must match a field name from the semantic model's measures or dimensions. | validation: maxLength 5120 - name: values | type: array | description: Values to compare against. For range conditions, provide exactly 2 values representing the start and end of the range. | validation: maxItems 100, maxLength 5120 - name: prefix | type: FilterPrefixEnum | description: Whether to match or negate the condition. Default: `IS` - enum: - IS: Positive match. For example, `IS` + `EQUAL` means "is equal to". - NOT: Negated match. For example, `NOT` + `EQUAL` means "is not equal to". - name: condition | type: FilterConditionEnum | description: Comparison condition to apply. Default: `EQUAL` - enum: - EQUAL: Value equals the filter value. - GREATER_THAN: Value is greater than the filter value. - GREATER_THAN_OR_EQUAL: Value is greater than or equal to the filter value. - LESS_THAN: Value is less than the filter value. - LESS_THAN_OR_EQUAL: Value is less than or equal to the filter value. - NULL: Value is null. - EMPTY: Value is an empty string. - START_WITH: String value starts with the filter value. - END_WITH: String value ends with the filter value. - CONTAINS_ANY: For strings, matches if any of the filter values appear as a substring. For arrays, matches if any of the filter values are present in the array. - RANGE_II: Inclusive start, inclusive end range. The value must fall within `[a, b]`. - RANGE_IE: Inclusive start, exclusive end range. The value must fall within `[a, b)`. - RANGE_EI: Exclusive start, inclusive end range. The value must fall within `(a, b]`. - RANGE_EE: Exclusive start, exclusive end range. The value must fall within `(a, b)`. - CONTAINS_ALL: For strings, matches if all filter values appear as substrings. For arrays, matches if all filter values are present in the array. param name: formattingEnabled | type: formattingEnabled | description: Whether to format numeric values as human-readable strings. For example, `1500` displays as `$1,500.00` or `1.5K` when enabled. Default: `false` param name: interval | type: DateTimeInterval | description: Date time interval | required: true - name: start | type: string | description: Period start date in UTC. | validation: format date-time - name: end | type: string | description: Period end date in UTC. | validation: format date-time - name: timezone | type: string | description: Timezone | validation: maxLength 1024 param name: paging | type: Paging | description: Paging - name: limit | type: integer | description: Number of items to load. | validation: minimum 0, maximum 5000, format int32 - name: offset | type: integer | description: Number of items to skip in the current sort order. | validation: minimum 0, format int32 param name: semanticModelId | type: semanticModelId | description: GUID of the semantic model to query. | required: true | validation: maxLength 5120 param name: sort | type: Sorting | description: Sorting options. - name: fieldName | type: string | description: Name of the field to sort the results by. | validation: maxLength 5120 - name: order | type: SortOrder | description: Sort direction. Default: `ASC` - enum: - ASC: Ascending order. - DESC: Descending order. - name: nullsLast | type: boolean | description: Whether to place null values last in the result set. Applies to descending order. Default: `false` param name: totalsIncluded | type: totalsIncluded | description: Whether to include a totals row in the response. When `true`, the `totals` field contains the sum of all numeric fields across the full (unpaginated) result set. Default: `false` Return type: QuerySemanticModelDataResponse - name: results | type: array | description: Retrieved data rows. | validation: maxItems 1000 - name: fields | type: Map | description: Map of field name to its value for this row. | validation: maxItems 100, format map - ONE-OF: - name: numericValue | type: number | description: Numeric value. | validation: format double - name: timestampValue | type: string | description: Date and time value. | validation: format date-time - name: booleanValue | type: boolean | description: Boolean value. - name: stringValue | type: string | description: String value. | validation: maxLength 5120 - name: arrayValue | type: ListValue | description: Array value. - name: values | type: array | description: - ONE-OF: - name: nullValue | type: | description: - name: numberValue | type: number | description: - name: stringValue | type: string | description: - name: boolValue | type: boolean | description: - name: structValue | type: object | description: - name: listValue | type: ListValue | description: - name: objectValue | type: object | description: Object value with key-value pairs. - name: formattedValue | type: string | description: Human-readable string representation of the value. Populated when `formattingEnabled` is `true` in the request. | validation: maxLength 5120 - name: pagingMetadata | type: PagingMetadata | description: Pagination metadata. - name: count | type: integer | description: Number of items returned in the response. | validation: format int32 - name: offset | type: integer | description: Offset that was requested. | validation: format int32 - name: totals | type: DataRow | description: Totals row with the sum of all numeric fields across the full result set. Returned only when `totalsIncluded` is `true`. Possible Errors: HTTP Code: 401 | Status Code: UNAUTHENTICATED | Application Code: NO_ACCOUNT_IDENTITY | Description: The caller isn't authenticated. Provide valid credentials and try again. ``` ### Examples ### Query semantic model data with sorting and totals. ```curl curl -X POST \ 'https://www.wixapis.com/analytics/semantic-model/v3/semantic-models/query-data' \ -H 'Content-type: application/json' \ -H 'Authorization: ' \ -d '{ "semanticModelId": "cad7fd34-2c8b-4dda-8296-3f9d47fb484d", "interval": { "start": "2024-06-01T00:00:00.000Z", "end": "2025-05-31T23:59:59.000Z" }, "fields": [ "traffic.referrer_category_name", "traffic.sessions_count", "traffic.views_count" ], "sort": { "fieldName": "traffic.sessions_count", "order": "DESC" }, "paging": { "limit": 5, "offset": 0 }, "formattingEnabled": true, "totalsIncluded": true }' ``` --- ## JavaScript SDK ### Schema ``` Method: wixClientAdmin.analytics.SemanticModelsService.querySemanticModelData(semanticModelId, options) Description: Retrieves data from a semantic model for the specified fields, filters, sorting, and paging. Query Semantic Model Data runs with these defaults, which you can override: - `paging.limit` is `50` - `paging.offset` is `0` To learn about working with Query methods, see [API Query Language](https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/data-retrieval/about-the-wix-api-query-language.md), [Sorting and Paging](https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/data-retrieval/about-sorting-and-paging.md), and [Field Projection](https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/data-retrieval/about-field-projection.md). # Note: If the parameter `a.b` is listed under required parameters, `b` is only required if `a` is also present. Required parameters: semanticModelId, options.interval, options.fields, options Method parameters: param name: options | type: QuerySemanticModelDataOptions none | required: true - name: interval | type: DateTimeInterval | description: Time interval for the data query. | required: true - name: start | type: Date | description: Period start date in UTC. - name: end | type: Date | description: Period end date in UTC. - name: timezone | type: string | description: Timezone | validation: maxLength 1024 - name: fields | type: array | description: List of field names to retrieve from the semantic model. Call `Get Semantic Model` to retrieve the semantic model's available fields. Fields with unmet dependencies (see the `dependencies` property in the semantic model schema) are silently omitted from results. | required: true | validation: maxItems 60, maxLength 5120 - name: sort | type: Sorting | description: Sort order for the results. Supports sorting by a single field only. - name: fieldName | type: string | description: Name of the field to sort the results by. | validation: maxLength 5120 - name: order | type: SortOrder | description: Sort direction. Default: `ASC` - enum: - ASC: Ascending order. - DESC: Descending order. - name: nullsLast | type: boolean | description: Whether to place null values last in the result set. Applies to descending order. Default: `false` - name: filters | type: array | description: Filters to apply to the data query. Supported conditions: `EQUAL`, `GREATER_THAN`, `GREATER_THAN_OR_EQUAL`, `LESS_THAN`, `LESS_THAN_OR_EQUAL`, `NULL`, `EMPTY`, `START_WITH`, `END_WITH`, `CONTAINS_ANY`, `CONTAINS_ALL`, `RANGE_II` (inclusive start, inclusive end), `RANGE_IE` (inclusive start, exclusive end), `RANGE_EI` (exclusive start, inclusive end), and `RANGE_EE` (exclusive start, exclusive end). | validation: maxItems 60 - name: field | type: string | description: Name of the field to filter by. Must match a field name from the semantic model's measures or dimensions. | validation: maxLength 5120 - name: values | type: array | description: Values to compare against. For range conditions, provide exactly 2 values representing the start and end of the range. | validation: maxItems 100, maxLength 5120 - name: prefix | type: FilterPrefixEnum | description: Whether to match or negate the condition. Default: `IS` - enum: - IS: Positive match. For example, `IS` + `EQUAL` means "is equal to". - NOT: Negated match. For example, `NOT` + `EQUAL` means "is not equal to". - name: condition | type: FilterConditionEnum | description: Comparison condition to apply. Default: `EQUAL` - enum: - EQUAL: Value equals the filter value. - GREATER_THAN: Value is greater than the filter value. - GREATER_THAN_OR_EQUAL: Value is greater than or equal to the filter value. - LESS_THAN: Value is less than the filter value. - LESS_THAN_OR_EQUAL: Value is less than or equal to the filter value. - NULL: Value is null. - EMPTY: Value is an empty string. - START_WITH: String value starts with the filter value. - END_WITH: String value ends with the filter value. - CONTAINS_ANY: For strings, matches if any of the filter values appear as a substring. For arrays, matches if any of the filter values are present in the array. - RANGE_II: Inclusive start, inclusive end range. The value must fall within `[a, b]`. - RANGE_IE: Inclusive start, exclusive end range. The value must fall within `[a, b)`. - RANGE_EI: Exclusive start, inclusive end range. The value must fall within `(a, b]`. - RANGE_EE: Exclusive start, exclusive end range. The value must fall within `(a, b)`. - CONTAINS_ALL: For strings, matches if all filter values appear as substrings. For arrays, matches if all filter values are present in the array. - name: paging | type: Paging | description: Pagination options. - name: limit | type: integer | description: Number of items to load. | validation: minimum 0, maximum 5000, format int32 - name: offset | type: integer | description: Number of items to skip in the current sort order. | validation: minimum 0, format int32 - name: formattingEnabled | type: boolean | description: Whether to format numeric values as human-readable strings. For example, `1500` displays as `$1,500.00` or `1.5K` when enabled. Default: `false` - name: totalsIncluded | type: boolean | description: Whether to include a totals row in the response. When `true`, the `totals` field contains the sum of all numeric fields across the full (unpaginated) result set. Default: `false` param name: semanticModelId | type: string | description: GUID of the semantic model to query. | required: true | validation: maxLength 5120 Return type: PROMISE - name: results | type: array | description: Retrieved data rows. | validation: maxItems 1000 - name: fields | type: Map | description: Map of field name to its value for this row. | validation: maxItems 100, format map - ONE-OF: - name: numericValue | type: number | description: Numeric value. - name: timestampValue | type: Date | description: Date and time value. - name: booleanValue | type: boolean | description: Boolean value. - name: stringValue | type: string | description: String value. | validation: maxLength 5120 - name: arrayValue | type: ListValue | description: Array value. - name: values | type: array | description: - ONE-OF: - name: nullValue | type: | description: - name: numberValue | type: number | description: - name: stringValue | type: string | description: - name: boolValue | type: boolean | description: - name: structValue | type: object | description: - name: listValue | type: ListValue | description: - name: objectValue | type: object | description: Object value with key-value pairs. - name: formattedValue | type: string | description: Human-readable string representation of the value. Populated when `formattingEnabled` is `true` in the request. | validation: maxLength 5120 - name: pagingMetadata | type: PagingMetadata | description: Pagination metadata. - name: count | type: integer | description: Number of items returned in the response. | validation: format int32 - name: offset | type: integer | description: Offset that was requested. | validation: format int32 - name: totals | type: DataRow | description: Totals row with the sum of all numeric fields across the full result set. Returned only when `totalsIncluded` is `true`. Possible Errors: HTTP Code: 401 | Status Code: UNAUTHENTICATED | Application Code: NO_ACCOUNT_IDENTITY | Description: The caller isn't authenticated. Provide valid credentials and try again. ``` ### Examples ### Query semantic model data with sorting and totals. ```javascript import { analyticsSemanticModel } from "@wix/analytics-semantic-model"; async function querySemanticModelData() { const response = await analyticsSemanticModel.querySemanticModelData( "cad7fd34-2c8b-4dda-8296-3f9d47fb484d", { "interval": { "start": "2024-06-01T00:00:00.000Z", "end": "2025-05-31T23:59:59.000Z" }, "fields": [ "traffic.referrer_category_name", "traffic.sessions_count", "traffic.views_count" ], "sort": { "fieldName": "traffic.sessions_count", "order": "DESC" }, "paging": { "limit": 5, "offset": 0 }, "formattingEnabled": true, "totalsIncluded": true } ); } /* Promise resolves to: { "results": [], "pagingMetadata": { "count": 0, "offset": 0 }, "totals": { "fields": { "traffic.referrer_category_name": { "formattedValue": "Unknown" }, "traffic.sessions_count": { "numericValue": 0, "formattedValue": "0" }, "traffic.views_count": { "numericValue": 0, "formattedValue": "0" } } } } */ ``` ### querySemanticModelData (self-hosted) Self-hosted SDK calls require you to [create a client](https://dev.wix.com/docs/sdk/articles/work-with-the-sdk/about-the-wix-client.md). ```javascript import { createClient } from '@wix/sdk'; import { analyticsSemanticModel } from '@wix/analytics-semantic-model'; // Import the auth strategy for the relevant access type // Import the relevant host module if needed const myWixClient = createClient ({ modules: { analyticsSemanticModel }, // Include the auth strategy and host as relevant }); async function querySemanticModelData(semanticModelId,options) { const response = await myWixClient.analyticsSemanticModel.querySemanticModelData(semanticModelId,options); }; ``` ---