> 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

# CreateCollection

# Package: externalDatabases

# Namespace: ExternalDatabaseService

# Method link: https://dev.wix.com/docs/api-reference/business-solutions/cms/external-databases/external-database-service-plugin/create-collection.md

## Introduction

Creates a new data collection.

---

## REST API

### Schema

```
 Method: createCollection
 Description: Creates a new data collection.
 URL: null
 Method: POST
 # Note: If the parameter `a.b` is listed under required parameters, `b` is only required if `a` is also present.
 Required parameters:  collection.id, collection.fields, collection.fields.key, collection.fields.type, collection.fields.encrypted
 Method parameters: 
   param name: collection | type: Collection   
        - name: id | type: string | description: GUID of the collection. | required: true
        - name: displayName | type: string | description: Collection display name as it appears in the CMS. For example, `My First Collection`. 
        - name: fields | type: array<Field> | description: Collection fields. | required: true
           - ONE-OF: 
              - name: singleReferenceOptions | type: SingleReferenceOptions | description:  
                 - name: referencedCollectionId | type: string | description: GUID of the referenced collection.  When the referring field is a single-reference field, it refers to the `_id` field of the referenced collection. 
              - name: multiReferenceOptions | type: MultiReferenceOptions | description:  
                 - name: referencedCollectionId | type: string | description: GUID of the referenced collection. 
                 - name: referencedCollectionFieldKey | type: string | description: Field GUID of the referenced field in the referenced collection. 
                 - name: referencedCollectionFieldDisplayName | type: string | description: Field display name of the referenced field in the referenced collection. 
              - name: arrayOptions | type: ArrayOptions | description:  
                 - ONE-OF: 
                    - name: singleReferenceOptions | type: SingleReferenceOptions | description:  
                    - name: multiReferenceOptions | type: MultiReferenceOptions | description:  
                    - name: arrayOptions | type: ArrayOptions | description:  
                    - name: objectOptions | type: ObjectOptions | description:  
                       - name: fields | type: array<ObjectField> | description: Fields within the object. 
                          - ONE-OF: 
                             - name: singleReferenceOptions | type: SingleReferenceOptions | description:  
                             - name: multiReferenceOptions | type: MultiReferenceOptions | description:  
                             - name: arrayOptions | type: ArrayOptions | description:  
                             - name: objectOptions | type: ObjectOptions | description:  
                          - name: key | type: string | description: Field GUID. 
                          - name: displayName | type: string | description: Field display name. 
                          - name: type | type: FieldType | description: Field type. 
                                     - enum: TEXT, NUMBER, DATE, DATETIME, IMAGE, BOOLEAN, DOCUMENT, URL, RICH_TEXT, VIDEO, ANY, ARRAY_STRING, ARRAY_DOCUMENT, AUDIO, TIME, LANGUAGE, RICH_CONTENT, MEDIA_GALLERY, ADDRESS, REFERENCE, MULTI_REFERENCE, OBJECT, ARRAY
                 - name: elementType | type: FieldType | description: Element data type. 
              - name: objectOptions | type: ObjectOptions | description:  
           - name: key | type: string | description: Field identifier. 
           - name: displayName | type: string | description: Field display name as it appears in the CMS. For example, `First Name`. 
           - name: description | type: string | description: Field description. 
           - name: type | type: FieldType | description: Field type. 
           - name: encrypted | type: boolean | description: Whether the field value is encrypted and sent as an object. Encryption and decryption are handled by Wix. Default: `false`. 
        - name: permissions | type: Permissions | description: Levels of permission for accessing and modifying data. These are defined by the lowest role needed to perform each action. 
           - name: insert | type: Role | description: Lowest role required to add a collection. 
                 - enum:
                 -     ADMIN: Site administrator.
                 -     SITE_MEMBER_AUTHOR: A signed-in user who inserted content to this collection.
                 -     SITE_MEMBER: Any signed-in user.
                 -     ANYONE: Any site visitor.
           - name: update | type: Role | description: Lowest role required to update a collection. 
           - name: remove | type: Role | description: Lowest role required to remove a collection. 
           - name: read | type: Role | description: Lowest role required to read a collection. 
 Return type: CreateCollectionResponse
  - name: collection | type: Collection | description: Details of the created collection. 
     - name: id | type: string | description: GUID of the collection. 
     - name: displayName | type: string | description: Collection display name as it appears in the CMS. For example, `My First Collection`. 
     - name: fields | type: array<Field> | description: Collection fields. 
        - ONE-OF: 
           - name: singleReferenceOptions | type: SingleReferenceOptions | description:  
              - name: referencedCollectionId | type: string | description: GUID of the referenced collection.  When the referring field is a single-reference field, it refers to the `_id` field of the referenced collection. 
           - name: multiReferenceOptions | type: MultiReferenceOptions | description:  
              - name: referencedCollectionId | type: string | description: GUID of the referenced collection. 
              - name: referencedCollectionFieldKey | type: string | description: Field GUID of the referenced field in the referenced collection. 
              - name: referencedCollectionFieldDisplayName | type: string | description: Field display name of the referenced field in the referenced collection. 
           - name: arrayOptions | type: ArrayOptions | description:  
              - ONE-OF: 
                 - name: singleReferenceOptions | type: SingleReferenceOptions | description:  
                 - name: multiReferenceOptions | type: MultiReferenceOptions | description:  
                 - name: arrayOptions | type: ArrayOptions | description:  
                 - name: objectOptions | type: ObjectOptions | description:  
                    - name: fields | type: array<ObjectField> | description: Fields within the object. 
                       - ONE-OF: 
                          - name: singleReferenceOptions | type: SingleReferenceOptions | description:  
                          - name: multiReferenceOptions | type: MultiReferenceOptions | description:  
                          - name: arrayOptions | type: ArrayOptions | description:  
                          - name: objectOptions | type: ObjectOptions | description:  
                       - name: key | type: string | description: Field GUID. 
                       - name: displayName | type: string | description: Field display name. 
                       - name: type | type: FieldType | description: Field type. 
                                 - enum: TEXT, NUMBER, DATE, DATETIME, IMAGE, BOOLEAN, DOCUMENT, URL, RICH_TEXT, VIDEO, ANY, ARRAY_STRING, ARRAY_DOCUMENT, AUDIO, TIME, LANGUAGE, RICH_CONTENT, MEDIA_GALLERY, ADDRESS, REFERENCE, MULTI_REFERENCE, OBJECT, ARRAY
                       - name: capabilities | type: FieldCapabilities | description: Capabilities the object field supports. 
                          - name: sortable | type: boolean | description: Whether the field can be used to sort the items in a collection. Default: `false`. 
                          - name: queryOperators | type: array<QueryOperator> | description: Query operators that can be used for this field. 
                                     - enum: EQ, LT, GT, NE, LTE, GTE, STARTS_WITH, ENDS_WITH, CONTAINS, HAS_SOME, HAS_ALL, EXISTS, URLIZED
              - name: elementType | type: FieldType | description: Element data type. 
           - name: objectOptions | type: ObjectOptions | description:  
        - name: key | type: string | description: Field identifier. 
        - name: displayName | type: string | description: Field display name as it appears in the CMS. For example, `First Name`. 
        - name: description | type: string | description: Field description. 
        - name: type | type: FieldType | description: Field type. 
        - name: capabilities | type: FieldCapabilities | description: Capabilities the collection supports. This is set by the external database and is ignored in the body of the request. 
        - name: encrypted | type: boolean | description: Whether the field value is encrypted and sent as an object. Encryption and decryption are handled by Wix. Default: `false`. 
     - name: capabilities | type: CollectionCapabilities | description: Capabilities the collection supports. This is set by the external database, and is ignored in the body of the request. 
        - name: dataOperations | type: array<DataOperation> | description: Data operations that can be performed on items in the collection. 
             - enum: QUERY, COUNT, QUERY_REFERENCED, AGGREGATE, DISTINCT, INSERT, UPDATE, REMOVE, TRUNCATE, INSERT_REFERENCES, REMOVE_REFERENCES
     - name: permissions | type: Permissions | description: Levels of permission for accessing and modifying data. These are defined by the lowest role needed to perform each action. 
        - name: insert | type: Role | description: Lowest role required to add a collection. 
             - enum:
             -     ADMIN: Site administrator.
             -     SITE_MEMBER_AUTHOR: A signed-in user who inserted content to this collection.
             -     SITE_MEMBER: Any signed-in user.
             -     ANYONE: Any site visitor.
        - name: update | type: Role | description: Lowest role required to update a collection. 
        - name: remove | type: Role | description: Lowest role required to remove a collection. 
        - name: read | type: Role | description: Lowest role required to read a collection. 
     - name: pagingMode | type: PagingMode | description: Whether the collection supports cursor- or offset-based paging. Each paging mode requires different configuration parameters. 
         - enum:
         -     OFFSET: Offset-based paging.
         -     CURSOR: Cursor-based paging.


```

### Examples

### Create a collection
```curl
curl -X POST https://external-db.example.com/v3/collections/create  \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'Authorization: <AUTH>' \
    -d '{
  "collection": {
    "id": "cities",
    "displayName": "Cities",
    "fields": [{
      "key": "name",
      "displayName": "Name",
      "description": "The name of the city",
      "type": "TEXT",
      "encrypted": false
    }, {
      "key": "country",
      "displayName": "Country",
      "description": "Country code",
      "type": "TEXT",
      "encrypted": false
    }, {
      "key": "pointsOfInterest",
      "displayName": "Points of interest",
      "type": "MULTI_REFERENCE",
      "multiReferenceOptions": {
        "referencedCollectionId": "pointsOfInterest",
        "referencedCollectionFieldKey": "cities",
        "referencedCollectionFieldDisplayName": "Cities"
      },
      "encrypted": false
    }, {
      "key": "_id",
      "displayName": "ID",
      "type": "TEXT",
      "encrypted": false
    }, {
      "key": "_createdDate",
      "displayName": "Created Date",
      "type": "DATETIME",
      "encrypted": false
    }, {
      "key": "_updatedDate",
      "displayName": "Updated Date",
      "type": "DATETIME",
      "encrypted": false
    }, {
      "key": "_owner",
      "displayName": "Owner",
      "type": "TEXT",
      "encrypted": false
    }],
    "permissions": {
      "insert": "ADMIN",
      "update": "ADMIN",
      "remove": "ADMIN",
      "read": "ANYONE"
    },
    "pagingMode": "UNKNOWN_PAGING_MODE"
  }
}'
```

---

## JavaScript SDK

### Schema

```
 Method: wixClientAdmin.externalDatabases.ExternalDatabaseService.createCollection(request, metadata)
 Description: Creates a new data collection.
 Method parameters:
   param name: metadata | type: Context | description: this message is not directly used by any service, it exists to describe the expected parameters that SHOULD be provided to invoked Velo methods as part of open-platform. e.g. SPIs, event-handlers, etc.. NOTE: this context object MUST be provided as the last argument in each Velo method signature.  Example: ```typescript export function wixStores_onOrderCanceled({ event, metadata }: OrderCanceledEvent) { ... } ``` 
        - name: requestId | type: string | description: A unique identifier of the request. You may print this GUID to your logs to help with future debugging and easier correlation with Wix's logs. 
        - name: currency | type: string | description: [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) 3-letter currency code. 
        - name: identity | type: IdentificationData | description: An object that describes the identity that triggered this request. 
           - ONE-OF: 
              - name: anonymousVisitorId | type: string | description: GUID of a site visitor that has not logged in to the site. 
              - name: memberId | type: string | description: GUID of a site visitor that has logged in to the site. 
              - name: wixUserId | type: string | description: GUID of a Wix user (site owner, contributor, etc.). 
              - name: appId | type: string | description: GUID of an app. 
        - name: languages | type: array | description: A string representing a language and region in the format of `"xx-XX"`. First 2 letters represent the language code according to ISO 639-1. This is followed by a dash "-", and then a by 2 capital letters representing the region according to ISO 3166-2. For example, `"en-US"`. 
        - name: instanceId | type: string | description: The service provider app's instance GUID. 
   param name: request | type: CreateCollectionRequest   
        - name: collection | type: Collection | description: Details of the collection to create. 
           - name: _id | type: string | description: GUID of the collection. 
           - name: displayName | type: string | description: Collection display name as it appears in the CMS. For example, `My First Collection`. 
           - name: fields | type: array<Field> | description: Collection fields. 
              - ONE-OF: 
                 - name: singleReferenceOptions | type: SingleReferenceOptions | description:  
                    - name: referencedCollectionId | type: string | description: GUID of the referenced collection.  When the referring field is a single-reference field, it refers to the `_id` field of the referenced collection. 
                 - name: multiReferenceOptions | type: MultiReferenceOptions | description:  
                    - name: referencedCollectionId | type: string | description: GUID of the referenced collection. 
                    - name: referencedCollectionFieldKey | type: string | description: Field GUID of the referenced field in the referenced collection. 
                    - name: referencedCollectionFieldDisplayName | type: string | description: Field display name of the referenced field in the referenced collection. 
                 - name: arrayOptions | type: ArrayOptions | description:  
                    - ONE-OF: 
                       - name: singleReferenceOptions | type: SingleReferenceOptions | description:  
                       - name: multiReferenceOptions | type: MultiReferenceOptions | description:  
                       - name: arrayOptions | type: ArrayOptions | description:  
                       - name: objectOptions | type: ObjectOptions | description:  
                          - name: fields | type: array<ObjectField> | description: Fields within the object. 
                             - ONE-OF: 
                                - name: singleReferenceOptions | type: SingleReferenceOptions | description:  
                                - name: multiReferenceOptions | type: MultiReferenceOptions | description:  
                                - name: arrayOptions | type: ArrayOptions | description:  
                                - name: objectOptions | type: ObjectOptions | description:  
                             - name: key | type: string | description: Field GUID. 
                             - name: displayName | type: string | description: Field display name. 
                             - name: type | type: FieldType | description: Field type. 
                                         - enum: TEXT, NUMBER, DATE, DATETIME, IMAGE, BOOLEAN, DOCUMENT, URL, RICH_TEXT, VIDEO, ANY, ARRAY_STRING, ARRAY_DOCUMENT, AUDIO, TIME, LANGUAGE, RICH_CONTENT, MEDIA_GALLERY, ADDRESS, REFERENCE, MULTI_REFERENCE, OBJECT, ARRAY
                    - name: elementType | type: FieldType | description: Element data type. 
                 - name: objectOptions | type: ObjectOptions | description:  
              - name: key | type: string | description: Field identifier. 
              - name: displayName | type: string | description: Field display name as it appears in the CMS. For example, `First Name`. 
              - name: description | type: string | description: Field description. 
              - name: type | type: FieldType | description: Field type. 
              - name: encrypted | type: boolean | description: Whether the field value is encrypted and sent as an object. Encryption and decryption are handled by Wix. Default: `false`. 
           - name: permissions | type: Permissions | description: Levels of permission for accessing and modifying data. These are defined by the lowest role needed to perform each action. 
              - name: insert | type: Role | description: Lowest role required to add a collection. 
                     - enum:
                     -     ADMIN: Site administrator.
                     -     SITE_MEMBER_AUTHOR: A signed-in user who inserted content to this collection.
                     -     SITE_MEMBER: Any signed-in user.
                     -     ANYONE: Any site visitor.
              - name: update | type: Role | description: Lowest role required to update a collection. 
              - name: remove | type: Role | description: Lowest role required to remove a collection. 
              - name: read | type: Role | description: Lowest role required to read a collection. 
 Return type: PROMISE<CreateCollectionResponse>
  - name: collection | type: Collection | description: Details of the created collection. 
     - name: _id | type: string | description: GUID of the collection. 
     - name: displayName | type: string | description: Collection display name as it appears in the CMS. For example, `My First Collection`. 
     - name: fields | type: array<Field> | description: Collection fields. 
        - ONE-OF: 
           - name: singleReferenceOptions | type: SingleReferenceOptions | description:  
              - name: referencedCollectionId | type: string | description: GUID of the referenced collection.  When the referring field is a single-reference field, it refers to the `_id` field of the referenced collection. 
           - name: multiReferenceOptions | type: MultiReferenceOptions | description:  
              - name: referencedCollectionId | type: string | description: GUID of the referenced collection. 
              - name: referencedCollectionFieldKey | type: string | description: Field GUID of the referenced field in the referenced collection. 
              - name: referencedCollectionFieldDisplayName | type: string | description: Field display name of the referenced field in the referenced collection. 
           - name: arrayOptions | type: ArrayOptions | description:  
              - ONE-OF: 
                 - name: singleReferenceOptions | type: SingleReferenceOptions | description:  
                 - name: multiReferenceOptions | type: MultiReferenceOptions | description:  
                 - name: arrayOptions | type: ArrayOptions | description:  
                 - name: objectOptions | type: ObjectOptions | description:  
                    - name: fields | type: array<ObjectField> | description: Fields within the object. 
                       - ONE-OF: 
                          - name: singleReferenceOptions | type: SingleReferenceOptions | description:  
                          - name: multiReferenceOptions | type: MultiReferenceOptions | description:  
                          - name: arrayOptions | type: ArrayOptions | description:  
                          - name: objectOptions | type: ObjectOptions | description:  
                       - name: key | type: string | description: Field GUID. 
                       - name: displayName | type: string | description: Field display name. 
                       - name: type | type: FieldType | description: Field type. 
                                 - enum: TEXT, NUMBER, DATE, DATETIME, IMAGE, BOOLEAN, DOCUMENT, URL, RICH_TEXT, VIDEO, ANY, ARRAY_STRING, ARRAY_DOCUMENT, AUDIO, TIME, LANGUAGE, RICH_CONTENT, MEDIA_GALLERY, ADDRESS, REFERENCE, MULTI_REFERENCE, OBJECT, ARRAY
                       - name: capabilities | type: FieldCapabilities | description: Capabilities the object field supports. 
                          - name: sortable | type: boolean | description: Whether the field can be used to sort the items in a collection. Default: `false`. 
                          - name: queryOperators | type: array<QueryOperator> | description: Query operators that can be used for this field. 
                                     - enum: EQ, LT, GT, NE, LTE, GTE, STARTS_WITH, ENDS_WITH, CONTAINS, HAS_SOME, HAS_ALL, EXISTS, URLIZED
              - name: elementType | type: FieldType | description: Element data type. 
           - name: objectOptions | type: ObjectOptions | description:  
        - name: key | type: string | description: Field identifier. 
        - name: displayName | type: string | description: Field display name as it appears in the CMS. For example, `First Name`. 
        - name: description | type: string | description: Field description. 
        - name: type | type: FieldType | description: Field type. 
        - name: capabilities | type: FieldCapabilities | description: Capabilities the collection supports. This is set by the external database and is ignored in the body of the request. 
        - name: encrypted | type: boolean | description: Whether the field value is encrypted and sent as an object. Encryption and decryption are handled by Wix. Default: `false`. 
     - name: capabilities | type: CollectionCapabilities | description: Capabilities the collection supports. This is set by the external database, and is ignored in the body of the request. 
        - name: dataOperations | type: array<DataOperation> | description: Data operations that can be performed on items in the collection. 
             - enum: QUERY, COUNT, QUERY_REFERENCED, AGGREGATE, DISTINCT, INSERT, UPDATE, REMOVE, TRUNCATE, INSERT_REFERENCES, REMOVE_REFERENCES
     - name: permissions | type: Permissions | description: Levels of permission for accessing and modifying data. These are defined by the lowest role needed to perform each action. 
        - name: insert | type: Role | description: Lowest role required to add a collection. 
             - enum:
             -     ADMIN: Site administrator.
             -     SITE_MEMBER_AUTHOR: A signed-in user who inserted content to this collection.
             -     SITE_MEMBER: Any signed-in user.
             -     ANYONE: Any site visitor.
        - name: update | type: Role | description: Lowest role required to update a collection. 
        - name: remove | type: Role | description: Lowest role required to remove a collection. 
        - name: read | type: Role | description: Lowest role required to read a collection. 
     - name: pagingMode | type: PagingMode | description: Whether the collection supports cursor- or offset-based paging. Each paging mode requires different configuration parameters. 
         - enum:
         -     OFFSET: Offset-based paging.
         -     CURSOR: Cursor-based paging.


```

### Examples

### Example of a `collection` return value
```javascript
import { externalDatabase } from '@wix/data/service-plugins';

externalDatabase.provideHandlers({

  createCollection: async ( payload ) => {
    const {request, metadata} = payload;
        // Use the `request` and `metadata` received from Wix and
        // apply custom logic.
      return {
        // Return your response exactly as documented to integrate with Wix.
        // Return value example:
        collection: {
          id: "cities",
          displayName: "Cities",
          fields: [
            {
              key: "_id",
              displayName: "ID",
              description: "The ID of the document",
              type: "TEXT",
              capabilities: {
                sortable: true,
                queryOperators: ["EQ", "LT", "GT", "LTE", "GTE"]
              },
              encrypted: false
            },
            {
              key: "name",
              displayName: "Name",
              description: "The name of the city",
              type: "TEXT",
              capabilities: {
                sortable: true,
                queryOperators: ["EQ", "STARTS_WITH"]
              },
              encrypted: false
            },
            {
              key: "country",
              displayName: "Country",
              description: "Country code",
              type: "TEXT",
              capabilities: {
                sortable: true,
                queryOperators: ["EQ"]
              },
              encrypted: false
            },
            {
              key: "pointsOfInterest",
              displayName: "Points of interest",
              type: "MULTI_REFERENCE",
              multiReferenceOptions: {
                referencedCollectionId: "pointsOfInterest"
              },
              encrypted: false
            },
            {
              key: "_createdDate",
              displayName: "Created date",
              description: "The date when the document was created",
              type: "DATETIME",
              capabilities: {
                sortable: false,
                queryOperators: []
              },
              encrypted: false
            },
            {
              key: "_updatedDate",
              displayName: "Updated date",
              description: "The date when the document was last updated",
              type: "DATETIME",
              capabilities: {
                sortable: false,
                queryOperators: []
              },
              encrypted: false
            },
            {
              key: "_owner",
              type: "TEXT",
              capabilities: {
                sortable: false,
                queryOperators: []
              },
              encrypted: false
            }
          ],
          capabilities: {
            dataOperations: ["QUERY", "COUNT"]
          },
          permissions: {
            insert: "ADMIN",
            update: "ADMIN",
            remove: "ADMIN",
            read: "ANYONE"
          },
          pagingMode: "OFFSET"
        }
      }
    }
});

```

### createCollection (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 { externalDatabase } from '@wix/data/service-plugins';
// Import the auth strategy for the relevant access type
// Import the relevant host module if needed

const myWixClient = createClient ({
  modules: { externalDatabase },
  // Include the auth strategy and host as relevant
});


async function createCollection(request,metadata) {
  const response = await myWixClient.externalDatabase.createCollection(request,metadata);
};
```

---