This skill provides guidance on using the CloudBase document database Web SDK for data operations in web applications.
Core Concepts
Initialization
Before using any database operations, initialize the CloudBase SDK:
import
cloudbase
from
"@cloudbase/js-sdk"
;
// UMD version
// If you are not using npm, And want to use UMD version instead. You should refer to https://docs.cloudbase.net/quick-start/#web-%E5%BF%AB%E9%80%9F%E4%BD%93%E9%AA%8C for latest version of UMD version.
const
app
=
cloudbase
.
init
(
{
env
:
"your-env-id"
,
// Replace with your environment id
}
)
;
const
db
=
app
.
database
(
)
;
const
_
=
db
.
command
;
// Get query operators
// ... login
Remember to sign in(auth) is *
REQUIRED
before actually querying the database.
Collection Reference
Access collections using:
db
.
collection
(
'collection-name'
)
Query Operators
CloudBase provides query operators via
db.command
(aliased as
_
):
_.gt(value)
- Greater than
_.gte(value)
- Greater than or equal
_.lt(value)
- Less than
_.lte(value)
- Less than or equal
_.eq(value)
- Equal to
_.neq(value)
- Not equal to
_.in(array)
- Value in array
_.nin(array)
- Value not in array
Basic Operations
Query Single Document
Query by document ID:
const
result
=
await
db
.
collection
(
'todos'
)
.
doc
(
'docId'
)
.
get
(
)
;
Query Multiple Documents
Query with conditions:
const
result
=
await
db
.
collection
(
'todos'
)
.
where
(
{
completed
:
false
,
priority
:
'high'
}
)
.
get
(
)
;
Note:
get()
returns 100 records by default, maximum 1000.
Query Methods Chaining
Combine methods for complex queries:
.where(conditions)
- Filter conditions
.orderBy(field, direction)
- Sort by field ('asc' or 'desc')
.limit(number)
- Limit results (default 100, max 1000)
.skip(number)
- Skip records for pagination
.field(object)
- Specify fields to return (true/false)
Advanced Features
For detailed information on specific topics, refer to:
Real-time data synchronization using watch() method
Setting up listeners for document changes
Handling real-time updates in chat and collaboration apps
Performance optimization and error handling
Common patterns for real-time applications
Security Rules
See
./security-rules.md
for:
Configuring database permissions
Simple permissions vs custom rules
Permission categories and usage
Security rule syntax and examples
Common Patterns
Error Handling
Always wrap database operations in try-catch:
try
{
const
result
=
await
db
.
collection
(
'todos'
)
.
get
(
)
;
console
.
log
(
result
.
data
)
;
}
catch
(
error
)
{
console
.
error
(
'Database error:'
,
error
)
;
}
Return Value Structure
Database operations return:
{
data
:
[
...
]
,
// Array of documents
// Additional metadata
}
Important Notes
Environment ID
Replace
"your-env-id"
with actual CloudBase environment ID
Default Limits
:
get()
returns 100 records by default
Collection Names
Use string literals for collection names
Geolocation Index
Geographic queries require proper indexing
Async/Await
All database operations are asynchronous
Best Practices
Initialize SDK once at application startup
Reuse database instance across the application
Use query operators for complex conditions
Implement pagination for large datasets
Select only needed fields to reduce data transfer
Handle errors appropriately
Create indexes for frequently queried fields
Coding Rules
It is
HIGHLY RECOMMENDED
to have a type definition and model layer for each collection in your document database. This will help you to avoid errors and make your code more robust. That would be the single source of truth for your database schema. Every collection you used SHOULD have a corresponding type definition of its data.
Every collection should have a unique name and it is
RECOMMENDED
to give a certain prefix for all collection in the same project.
Collections should have well defined and meaningful security rules(policy) for create, read, write and delete permission according to the business logic. Details refer to
./security-rules.md
. When writing expressions in security rules, The type definition of the collection mention above can be used as the type reference.
Quick Reference
Common query examples:
// Simple query
db
.
collection
(
'todos'
)
.
where
(
{
status
:
'active'
}
)
.
get
(
)
// With operators
db
.
collection
(
'users'
)
.
where
(
{
age
:
_
.
gt
(
18
)
}
)
.
get
(
)
// Pagination
db
.
collection
(
'posts'
)
.
orderBy
(
'createdAt'
,
'desc'
)
.
skip
(
20
)
.
limit
(
10
)
.
get
(
)
// Field selection
db
.
collection
(
'users'
)
.
field
(
{
name
:
true
,
email
:
true
,
_id
:
false
}
)
.
get
(
)
For more detailed examples and advanced usage patterns, refer to the companion reference files in this directory.
Error handling
EVERY
database operation(including
get()
,
add()
,
update()
,
delete()
etc)should check the return value's code for any errors. For example:
const
result
=
await
db
.
collection
(
'todos'
)
.
add
(
newTodo
)
;
if
(
typeof
result
.
code
===
'string'
)
{
// Handle error ...
}
Error
MUST
be handled with detail and human-readable message and friendly UI.