Question about using unique indexes for Custom Entities

[gyutaelee]

Hello BrainCloud Support Team,

I would like to ask about using unique indexes with Custom Entities.

We are currently using Custom Entity with the entityType FOLLOW, and we tried to create an index named test_index with the unique option enabled.

However, the following error occurred:

Error Code: 3010308
Error Message: Error adding custom entity index test_index for entityType FOLLOW
Exception: Index cannot be created with 'unique' option as prevents sharding of custom collection.
Exception message: Index cannot be created with 'unique' option as prevents sharding of custom collection.

We would like to prevent duplicate values for a specific field in this Custom Entity.

Could you please confirm whether Custom Entity indexes support the unique option?

If unique indexes are not supported due to sharding, could you recommend the best alternative approach to enforce uniqueness for a field in Custom Entity?

Thank you.

Best regards,
Gyutae Lee

[JasonL]

Hi @gyutaelee,
Currently, brainCloud blocks unique indexes on all custom collections as a blanket safeguard. The check happens unconditionally before the system even evaluates whether your collection is owned or sharded, so it rejects the unique option with that error.

We can manually add the unique index for your FOLLOW collection on our end. Please send us a request with:

1. Your appId
2. The entityType (is it FOLLOW only?)
3. The field name(s) that need uniqueness
4. The desired index name (e.g., test_index)

Once we receive your request, we'll add the uniqueness constraint for you directly.

[gyutaelee]

Hello brainCloud team,

We would like to request a unique compound index for our Custom Entity type FOLLOW.

Our App ID is 15389.

The FOLLOW entity stores follow relations with the following data shape:

{
  "followerId": "profileId_A",
  "followingId": "profileId_B",
  "createdAt": 1770000000000
}

We want to prevent duplicate follow relations for the same follower/following pair.

Entity Type: FOLLOW

Unique index name: followerId_followingId_unique

Keys:

{ "data.followerId": 1, "data.followingId": 1 }

Options:

{ "unique": true, "background": true }

We already have a non-unique index with the same key pattern:

Index name: followerId_followingId

Keys:

{ "data.followerId": 1, "data.followingId": 1 }

If needed, please replace this existing non-unique index with the unique version.

This feature has not been released to production yet, so we can clean up or reset the FOLLOW data before the unique index is applied if necessary.

We also have a few questions:

1. If this unique index is manually added to the Development app, will it be included automatically when we deploy or migrate to Staging/Production?
2. Or does this unique index need to be manually applied per app/environment?
3. If it must be applied per environment, can we provide the appIds for Development, Staging, and Production so you can add the same index to each app?
4. Are manually added Custom Entity indexes included in brainCloud deploy/migrate/export-import workflows?
5. If there are existing duplicate rows for the same data.followerId + data.followingId pair, will the unique index creation fail?
6. Is there any expected downtime, lock, write failure, or performance impact while this index is being created?
7. After the index is applied, what is the recommended way to verify that the unique index exists in each environment?

Thank you.

[JasonL]

Hi @gyutaelee, thanks for the detailed request. We will add a unique compound index for your FOLLOW Custom Entity.

About Your Questions:

1. Will this unique index auto-deploy to Staging/Production?
   No. Because brainCloud's API blocks unique indexes at the code level (to prevent sharding issues), the deployer does not know about manually added indexes.

2. Does this need to be applied per app/environment manually?
   Yes. Each brainCloud app (Dev/Staging/Prod) is a separate appId with its own physical MongoDB collection.

3. Can we provide appIds for Dev/Staging/Prod so you can add the index to each?
   Yes, absolutely. Please reply with the App IDs for your Staging and Production environments. Once we have them, we'll apply the same unique index to all three environments.

4. Are manually added Custom Entity indexes included in deploy/migrate/export-import workflows?
   No. The deploy pipeline is config-driven. Any index added directly via MongoDB (outside the Portal/API) is invisible to ImportExportService.

5. If there are existing duplicate rows, will unique index creation fail?
   Yes. MongoDB returns duplicate key error and aborts the entire index build. Since you mentioned the feature isn't in production yet, you can safely reset/clean up FOLLOW data before we apply the index to avoid this. We may need to check for duplicates first.

6. Is there expected downtime, lock, write failure, or performance impact?
   No hard downtime Index builds are non-blocking: reads and writes continue during the build.

7. How to verify the unique index exists after application?
   You can verify it from the Indexes tab of app/design/cloud-data/custom-entities/FOLLOW from portal, or call the method sysListIndexes() via API Explorer.

[Paul Winterhalder]

Hi @gyutaelee,

The unique option has been added to the existing followerId_followingId index of the FOLLOW custom entity.

I also added it to the staging and production apps in the same team.

Have a good week!

Paul.
[PS - we have plans to allow the creation of unique indexes via our portal soon...]

[gyutaelee]

Hello,

Thank you for your reply and for adding the option to the FOLLOW entity.

I checked the custom index settings again, but I still cannot see the added option on my side.

In the FOLLOW entity, under Custom Indexes > followerId_followingId > Options, I only see the following:

{
  "name": "followerId_followingId"
}

Could you please let me know if there is another place where I should check this option, or if there is any additional step required for it to appear?

Thank you.

[JasonL]

Hi @gyutaelee, have you tried calling the sysListIndexes method from the API Explorer to verify the index, as mentioned earlier? The Portal’s Custom Indexes UI may not always reflect the underlying MongoDB index options correctly for manually adjusted indexes like unique, so sysListIndexes is the more reliable way to confirm what’s actually on the collection. So run CustomEntity > SysListIndexes in API Explorer and check the returned index list for followerId_followingId and its unique flag.

[gyutaelee]

Hi,

Thank you for guiding me on how to check it.

I verified the indexes for the FOLLOW entity using CustomEntity > SysListIndexes in the API Explorer, and confirmed that unique: true is correctly applied to the followerId_followingId index.

The confirmed response is as follows:

{
  "name": "followerId_followingId",
  "key": {
    "data.followerId": 1,
    "data.followingId": 1
  },
  "background": true,
  "unique": true
}

Thank you for your help!

[gyutaelee]

Hello @JasonL @Paul-Winterhalder ,

I have an additional request.

Could you please apply the unique: true option to the following two indexes on the Custom Entity REFERRAL_CODE for App ID 15389?

• code
• referrerId

It would be appreciated if you could keep the existing index names and key patterns unchanged, and only add the unique option.

Thank you for your help.

[Paul Winterhalder]

Hi @gyutaelee - this has been done!

[gyutaelee]

@Paul-Winterhalder Thank you!