Search.../
  1. APIs

queryLabels( )

Developer Preview

Creates a query to retrieve a list of labels.

Description

The queryLabels() function builds a query to retrieve a list of labels and returns a LabelsQueryBuilder object.

The returned object contains the query definition, which is used to run the query using the find() function.

You can refine the query by chaining LabelsQueryBuilder functions onto the query. LabelsQueryBuilder functions enable you to filter, sort, and control the results that queryLabels() returns.

queryLabels() runs with the following LabelsQueryBuilder defaults, which you can override:

  • skip(0)
  • limit(50)
  • descending('_createdDate')

The following LabelsQueryBuilder functions are supported for queryLabels(). For a full description of the Labels object, see the object returned for the items property in LabelsQueryResult.

PROPERTYSUPPORTED FILTERS & SORTING
namespaceeq(),ne()
keyeq(),ne(),in()
displayNameeq(),ne(),in(),startsWith(),ascending(),descending()
labelTypeeq()
_createdDateeq(),ne(),gt(),lt(),ge(),le(),ascending(),descending()
_updatedDateeq(),ne(),gt(),lt(),ge(),le(),ascending(),descending()
Admin Method

This function requires elevated permissions to run. This function is not universal and runs only on the backend.

Syntax

function queryLabels(options: QueryLabelsOptions): LabelsQueryBuilder

queryLabels Parameters

NAME
TYPE
DESCRIPTION
options
Optional
QueryLabelsOptions

Language options.

Returns

Return Type:

LabelsQueryBuilder

Was this helpful?

Retrieve all labels (dashboard page code)

Copy Code
1import { labels } from 'wix-crm.v2';
2

3export async function myQueryLabelsFunction() {
4  
5  try {
6    const queryResults = await labels.queryLabels()
7      .find();
8

9    const items = queryResults.items;
10    const firstItem = items[0];
11    const pageSize = queryResults.pageSize;
12    const hasNext = queryResults.hasNext();
13    const hasPrev = queryResults.hasPrev();
14    const length = queryResults.length;
15    const query = queryResults.query;
16    console.log('Retrieved items:', items);
17    
18    return items;
19  } catch (error) {
20    console.log(error);
21    // Handle the error
22

23  }
24}
25

26/* Returns items:
27 * [
28 *   {
29 *     "namespace": "custom",
30 *     "namespaceDisplayName": "Labels",
31 *     "key": "custom.at-risk",
32 *     "displayName": "At Risk",
33 *     "labelType": "USER_DEFINED",
34 *     "legacyId": "65bd6a68-e10e-4831-8d92-c90e75be1570",
35 *     "_createdDate": "2023-12-25T08:38:36.000Z",
36 *     "_updatedDate": "2023-12-25T08:38:36.000Z"
37 *   },
38 *   {
39 *     "namespace": "custom",
40 *     "namespaceDisplayName": "Labels",
41 *     "key": "custom.active-customer",
42 *     "displayName": "Active Customer",
43 *     "labelType": "USER_DEFINED",
44 *     "legacyId": "74f1e5c6-d9d5-4485-b272-13081ea35f38",
45 *     "_createdDate": "2023-12-25T06:13:21.000Z",
46 *     "_updatedDate": "2023-12-25T06:13:21.000Z"
47 *   },
48 *   {
49 *     "namespace": "custom",
50 *     "namespaceDisplayName": "Labels",
51 *     "key": "custom.contact",
52 *     "displayName": "Contact",
53 *     "labelType": "USER_DEFINED",
54 *     "legacyId": "5fec05f8-eb03-4243-ad46-4c24535144f6",
55 *     "_createdDate": "2023-12-11T07:33:35.000Z",
56 *     "_updatedDate": "2023-12-11T07:33:35.000Z"
57 *   },
58 *   {
59 *     "namespace": "contacts",
60 *     "namespaceDisplayName": "Labels",
61 *     "key": "contacts.customers",
62 *     "displayName": "Customers",
63 *     "labelType": "SYSTEM",
64 *     "legacyId": "contacts_server/customers"
65 *   },
66 *   {
67 *     "namespace": "contacts",
68 *     "namespaceDisplayName": "Labels",
69 *     "key": "contacts.contacted-me",
70 *     "displayName": "Contacted Me",
71 *     "labelType": "SYSTEM",
72 *     "legacyId": "contacts_server/contacted_me"
73 *   }
74 * ]
75 */
Retrieve all labels (export from backend code)

Copy Code
1import { Permissions, webMethod } from 'wix-web-module';
2import { labels } from 'wix-crm.v2';
3import { elevate } from 'wix-auth';
4

5export const myQueryLabelsFunction = webMethod(Permissions.Anyone, async () => {
6  try {
7    const elevatedQueryLabels = elevate(labels.queryLabels);
8    const queryResults = await elevatedQueryLabels()
9      .find();
10

11    const items = queryResults.items;
12    const firstItem = items[0];
13    const pageSize = queryResults.pageSize;
14    const hasNext = queryResults.hasNext();
15    const hasPrev = queryResults.hasPrev();
16    const length = queryResults.length;
17    const query = queryResults.query;
18    console.log('Retrieved items:', items);
19    
20    return items;
21  } catch (error) {
22    console.log(error);
23    // Handle the error
24

25  }
26});
27

28/* Returns items:
29 * [
30 *   {
31 *     "namespace": "custom",
32 *     "namespaceDisplayName": "Labels",
33 *     "key": "custom.at-risk",
34 *     "displayName": "At Risk",
35 *     "labelType": "USER_DEFINED",
36 *     "legacyId": "65bd6a68-e10e-4831-8d92-c90e75be1570",
37 *     "_createdDate": "2023-12-25T08:38:36.000Z",
38 *     "_updatedDate": "2023-12-25T08:38:36.000Z"
39 *   },
40 *   {
41 *     "namespace": "custom",
42 *     "namespaceDisplayName": "Labels",
43 *     "key": "custom.active-customer",
44 *     "displayName": "Active Customer",
45 *     "labelType": "USER_DEFINED",
46 *     "legacyId": "74f1e5c6-d9d5-4485-b272-13081ea35f38",
47 *     "_createdDate": "2023-12-25T06:13:21.000Z",
48 *     "_updatedDate": "2023-12-25T06:13:21.000Z"
49 *   },
50 *   {
51 *     "namespace": "custom",
52 *     "namespaceDisplayName": "Labels",
53 *     "key": "custom.contact",
54 *     "displayName": "Contact",
55 *     "labelType": "USER_DEFINED",
56 *     "legacyId": "5fec05f8-eb03-4243-ad46-4c24535144f6",
57 *     "_createdDate": "2023-12-11T07:33:35.000Z",
58 *     "_updatedDate": "2023-12-11T07:33:35.000Z"
59 *   },
60 *   {
61 *     "namespace": "contacts",
62 *     "namespaceDisplayName": "Labels",
63 *     "key": "contacts.customers",
64 *     "displayName": "Customers",
65 *     "labelType": "SYSTEM",
66 *     "legacyId": "contacts_server/customers"
67 *   },
68 *   {
69 *     "namespace": "contacts",
70 *     "namespaceDisplayName": "Labels",
71 *     "key": "contacts.contacted-me",
72 *     "displayName": "Contacted Me",
73 *     "labelType": "SYSTEM",
74 *     "legacyId": "contacts_server/contacted_me"
75 *   }
76 * ]
77 */
Retrieve labels with specified labelType

Copy Code
1import { Permissions, webMethod } from 'wix-web-module';
2import { labels } from 'wix-crm.v2';
3import { elevate } from 'wix-auth';
4

5export const myQueryLabelsFunction = webMethod(Permissions.Anyone, async () => {
6  try {
7    const elevatedQueryLabels = elevate(labels.queryLabels);
8    const queryResults = await elevatedQueryLabels()
9      .eq("labelType", "USER_DEFINED")
10      .find();
11

12    const items = queryResults.items;
13    const firstItem = items[0];
14    const pageSize = queryResults.pageSize;
15    const hasNext = queryResults.hasNext();
16    const hasPrev = queryResults.hasPrev();
17    const length = queryResults.length;
18    const query = queryResults.query;
19    console.log('Retrieved items:', items);
20    
21    return items;
22  } catch (error) {
23    console.log(error);
24    // Handle the error
25

26  }
27});
28

29/* Returns items:
30 * [
31 *   {
32 *     "namespace": "custom",
33 *     "namespaceDisplayName": "Labels",
34 *     "key": "custom.at-risk",
35 *     "displayName": "At Risk",
36 *     "labelType": "USER_DEFINED",
37 *     "legacyId": "65bd6a68-e10e-4831-8d92-c90e75be1570",
38 *     "_createdDate": "2023-12-25T08:38:36.000Z",
39 *     "_updatedDate": "2023-12-25T08:38:36.000Z"
40 *   },
41 *   {
42 *     "namespace": "custom",
43 *     "namespaceDisplayName": "Labels",
44 *     "key": "custom.active-customer",
45 *     "displayName": "Active Customer",
46 *     "labelType": "USER_DEFINED",
47 *     "legacyId": "74f1e5c6-d9d5-4485-b272-13081ea35f38",
48 *     "_createdDate": "2023-12-25T06:13:21.000Z",
49 *     "_updatedDate": "2023-12-25T06:13:21.000Z"
50 *   },
51 *   {
52 *     "namespace": "custom",
53 *     "namespaceDisplayName": "Labels",
54 *     "key": "custom.contact",
55 *     "displayName": "Contact",
56 *     "labelType": "USER_DEFINED",
57 *     "legacyId": "5fec05f8-eb03-4243-ad46-4c24535144f6",
58 *     "_createdDate": "2023-12-11T07:33:35.000Z",
59 *     "_updatedDate": "2023-12-11T07:33:35.000Z"
60 *   }
61 * ]
62 */
63
Add labels to a contact form as checkbox options

This function uses queryLabels() to retrieve specific labels and then uses those label's display names as checkbox options for a checkbox group element on a contact form.

Copy Code
1/**********************************
2 * Backend code - contacts.web.js *
3 **********************************/
4

5import { Permissions, webMethod } from 'wix-web-module';
6import { labels } from 'wix-crm.v2';
7import { elevate } from 'wix-auth';
8

9

10export const addLabelsAsCheckboxOptions = webMethod(Permissions.Anyone, async () => {
11

12  try {
13    // Query specific labels to use as checkbox options
14    const elevatedQueryLabels = elevate(labels.queryLabels);
15    const myLabels = await elevatedQueryLabels()
16    .startsWith('displayName', "Contact by")
17    .find();
18

19    return myLabels.items
20

21  } catch (error) {
22    // Handle the error
23    console.log(error);
24  }
25});
26

27/*************
28 * Page code *
29 *************/
30

31import { addLabelsAsCheckboxOptions } from 'backend/labelsBackend.web';
32

33// Trigger when the email input field on a contact form is clicked
34export async function inputEmail_click_1(event) {
35

36  try {
37    let checkboxLabelOptions = [];
38    const labels = await addLabelsAsCheckboxOptions();
39

40    // Add label display names to the array used to hold the checkbox options
41    labels.forEach(item => {
42      checkboxLabelOptions.push({label: item.displayName, value: item.key});
43    });
44

45    // Set the checkbox group options as the label display names
46    $w('#checkboxGroup2').options = checkboxLabelOptions;
47    // Display the checkbox group element on the form
48    $w('#checkboxGroup2').show();
49  } catch (error) {
50    console.log(error)
51  }
52}