References
Overview of collection references
From your collection, you can reference other collections, taxonomies, users, or roles. By default, all references are saved as IDs. For referenced collections and taxonomies we allow using left joins in Find and FindOne requests for the first reference level. Unfortunately, that is not possible with user and role references and will require additional server calls.
For deeper and more customized referencing, use your own aggregates.

References are added using the Select field in your collection builder. When configuring it you can select one of the references - role, user, collection, or taxonomy. You also may specify it as a single (one to one) or multiple (one to many) references.
Reference field in collection builder

As mentioned, references can be used in Find and FindOne requests. You also need to pass a few parameters into one of these requests.
Parameter
Type
Description
referencedFields
array of objects
Fields that should be left joined. By default, if this is not passed, nothing is referenced and you will get only the IDs of your referenced records or terms.
addReferencesFirst
bool
By default referencing is done after your main collections records have been processed (filters, sort, projection, pagination applied).
If this is set to true, referencing is done first and you can apply your top-level filters, sort, and projection based on these resolved references (because the referenced fields will now be objects or arrays instead of IDs). Though setting this to true will slow down the response.

The following shows the form ofreferencedFieldsparameter. It is a list of objects where object defines parameters for each field to join. The one required value is name. All others are optional.
[
{
"name": "field1"
},
{
"name": "field2",
"pageSize": 10,
"pageNumber": 0,
"sort": "{ \"name\": 1 }",
"projection": "{ \"name\": 1 }"
}
]
All of the parameters defined in each of the objects are applied to joined records.
Parameter
Type
Description
Available In
name
string
Name of the field to join.
One to one or one to many reference.
pageSize
integer
Amount of joined records to return.
One to many (multiple) reference.
pageNumber
integer
The page of joined records to return.
One to many (multiple) reference.
sort
string
How to sort joined records.
One to many (multiple) reference.
projection
string
What fields to return from each of the joined record. Only inclusive projection is allowed (can only use 1 for fields, not 0).
One to one or one to many reference.

Let's say you have a record that is referencing another collection. You have two collections - person and company. In the database, your records could look like the following.

Here the company field is a reference to some record inside the company collection.
{ "_id": "person_id_1", "name": "John", "company": "comp_id_1" }

{ "_id": "comp_id_1", "name": "CodeMash" }
If not specifically specifying which fields to left join, then in response you will get the same record as shown in person example record. Now if we passed the following as referencedFields parameter:
[ { "name": "company" } ]
We would get a response that would look like this:
{
"_id": "person_id_1",
"name": "John",
"company": { "_id": "comp_id_1", "name": "CodeMash" }
}

The following shows how to use referencing from our provided SDKs.
.NET
Node
var client = new CodeMashClient(ApiKey, ProjectId);
var repository = new CodeMashRepository<ReferencingEntity>(client);
โ€‹
var referencedFields = new List<CollectionReferenceField>
{
// Including field1
new CollectionReferenceField
{
Name = "field1",
},
// Including field2
new CollectionReferenceField
{
Name = "field2",
PageSize = 10,
PageNumber = 0
},
};
โ€‹
// Setting sort parameter for a field2
referencedFields[1]
.SetSort(Builders<ReferencedEntity>.Sort.Descending(x => x.Date));
// Setting projection parameter for a field2
referencedFields[1]
.SetProjection(Builders<ReferencedEntity>
.Projection.Include(x => x.Date).Include(x => x.Id));
โ€‹
var response = await repository.FindAsync(
x => true,
new DatabaseFindOptions
{
ReferencedFields = referencedFields
}
);
The classes used in the example above are ReferencingEntity and ReferencedEntity. They could look something like this:
[Collection("referencing-entity")]
public class ReferencingEntity : Entity
{
[Field("field1")]
public ReferencedEntity FirstReference { get; set; }
[Field("field2")]
public List<ReferencedEntity> SecondReference { get; set; }
}
โ€‹
[Collection("referenced-entity")]
public class ReferencedEntity: Entity
{
[Field("date")]
public DateTime Date { get; set; }
}
โ€‹

If you only need id/name pair from reference, then you can use basic references without much configuration. These are controlled by 4 parameters.
Parameter
Type
Description
includeUserNames
bool
Includes the user's display label and id into a response.
includeRoleNames
bool
Includes the role's display name and value name.
includeCollectionNames
bool
Includes record's display label and id into a response.
includeTermNames
bool
Includes the term's title and id into a response.
The following shows examples of returned objects by using any of the parameters.
// When includeUserNames is true
{
"name": "John Doe",
"id": "{USER_ID}"
}
โ€‹
// When includeRoleNames is true
{
"name": "authenticated",
"displayName": "Authenticated"
}
โ€‹
// When includeCollectionNames is true
{
"name": "My Text Value",
"id": "{RECORD_ID}",
"collectionName": "referenced-collection-name"
}
โ€‹
// When IncludeTermNames is true
{
"name": "My Term Title",
"id": "{TERM_ID}",
"taxonomyName": "referenced-taxonomy-"
}
Last modified 2yr ago
Copy link
On this page
How to add references
How to use
Form of referencing field
Expected response
Usage in SDK
Basic references