field Documentation

1. Project Overview & Quickstart (nocobase/field) Copy Chapter

field

Open-source repository nocobase/field

Repository Details Copy Section

• Repository: nocobase/field
• Primary Language: Code

Note: High-volume repository documentation is actively indexed and synchronized by YakaAI.

2. Official Technical Reference & Guides (nocobase/docs) Copy Chapter

File: README.md Copy Chapter

NocoBase V1 Documentation (Archived)

This repository is archived and no longer maintained. V2 documentation lives in the main repository: nocobase/nocobase (under the docs/ directory). For the latest docs, visit docs.nocobase.com.

If you need to access the V1 documentation, you can run it locally:

Local Development Copy Chapter

git clone https://github.com/nocobase/docs.git
cd docs
yarn install

# Run English docs
yarn dev:en

# Run Chinese docs
yarn dev

# Run French docs
yarn dev:fr

# Run Japanese docs
yarn dev:ja

# Run Russian docs
yarn dev:ru

Build Copy Chapter

yarn build

Note: yarn dev and yarn dev:en cannot be run at the same time.

File: package.json Copy Chapter

{
"name": "nocobase-docs",
"version": "0.0.1",
"description": "A static site based on dumi",
"scripts": {
"start": "npm run dev",
"dev": "dumi dev",
"dev:en": "cross-env DOC_LANG=en-US dumi dev",
"dev:fr": "cross-env DOC_LANG=fr-FR dumi dev",
"dev:ja": "cross-env DOC_LANG=ja-JP dumi dev",
"dev:ru": "cross-env DOC_LANG=ru-RU dumi dev",
"build": "dumi build",
"build:en": "cross-env DOC_LANG=en-US dumi build",
"build:fr": "cross-env DOC_LANG=fr-FR dumi build",
"build:ja": "cross-env DOC_LANG=ja-JP dumi build",
"build:ru": "cross-env DOC_LANG=ru-RU dumi build",
"prepare": "husky install && dumi setup"
},
"authors": [],
"license": "MIT",
"commitlint": {
"extends": [
"@commitlint/config-conventional"
]
},
"lint-staged": {
"*.{md,json}": [
"prettier --write --no-error-on-unmatched-pattern"
]
},
"devDependencies": {
"@alicloud/cdn20180510": "^4.2.2",
"@commitlint/cli": "^18.2.0",
"@commitlint/config-conventional": "^18.1.0",
"ali-oss": "^6.1.0",
"cross-env": "^7.0.3",
"dumi": "^2.2.14",
"husky": "^8.0.3",
"lint-staged": "^15.0.2",
"prettier": "^3.0.3"
},
"dependencies": {
"@formulajs/formulajs": "^4.4.9",
"@nocobase/client": "^0.21.0-alpha.6",
"axios-mock-adapter": "1.22.0",
"cytoscape": "^3.23.0",
"dumi-theme-nocobase": "^0.2.31",
"moment": "^2.30.1",
"sucrase": "^3.0.0",
"vditor": "^3.10.8"
},
"volta": {
"node": "20.14.0",
"yarn": "1.22.19"
},
"packageManager": "[email protected]+sha512.a6b2f7906b721bba3d67d4aff083df04dad64c399707841b7acf00f6b133b7ac24255f2652fa22ae3534329dc6180534e98d17432037ff6fd140556e2bb3137e"
}

File: tsconfig.json Copy Chapter

{
"compilerOptions": {
"jsx": "react",
"strict": true,
"skipLibCheck": true,
"noImplicitAny": false,
"esModuleInterop": true,
"baseUrl": "./",
"paths": {
"@@/": [".dumi/tmp/"]
}
},
"include": [".dumirc.ts"]
}

File: docs/en-US/components.md Copy Chapter

Components

File: docs/en-US/index.md Copy Chapter

Index

File: docs/en-US/_partials/commercial-installation.md Copy Chapter

Installation Copy Chapter

This plugin is a commercial plugin, which needs to be uploaded and activated through the plugin manager：

File: docs/en-US/api/actions.md Copy Chapter

@nocobase/actions

Overview Copy Chapter

The @nocobase/actions package encapsulates frequently used CRUD-related methods. By simply registering it with the ResourceManager, CRUD operation interfaces can be globally added to system resources.

Basic Usage Copy Section

import * as actions from `@nocobase/actions`;

const resourceManager = new ResourceManager({
  // ...options
});

resourceManager.registerActionHandlers(actions);

Action Methods Copy Chapter

create Copy Section

Creates a resource. POST /api/<resource>:create.

curl "http://localhost:13000/api/users:create" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"username": "admin"}'

Request Body

list Copy Section

Retrieves a list of resources. GET /api/<resource>:list.

curl -X GET http://localhost:13000/api/users:list

Parameters

get Copy Section

Retrieves a specific resource. GET /api/<resource>:get.

curl -X GET http://localhost:13000/api/users:get?filterByTk=1

Parameters

update Copy Section

Updates one or more resources. PUT /api/<resource>:update.

curl "http://localhost:13000/api/users:update?filterByTk=1" \
  -X PUT \
  -H "Content-Type: application/json" \
  -d '{"username": "admin"}'

Parameters

Note: At least one of filter or filterByTk must be provided.

Request Body

destroy Copy Section

Deletes one or more resources. DELETE /api/<resource>:destroy.

curl -X DELETE http://localhost:13000/api/users:destroy?filterByTk=1

Parameters

Note: At least one of filter or filterByTk must be provided.

firstOrCreate Copy Section

Retrieves or creates a resource. POST /api/<resource>:firstOrCreate.

curl "http://localhost:13000/api/users:firstOrCreate?filterKeys[]=username" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "nickname": "Admin"}'

Parameters

Request Body

updateOrCreate Copy Section

Updates or creates a resource. POST /api/<resource>:updateOrCreate.

curl "http://localhost:13000/api/users:updateOrCreate?filterKeys[]=username" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "nickname": "Admin"}'

Parameters

Request Body

move Copy Section

Moves resources, adjusting the order. Typically used for drag-and-drop sorting in pages. POST /api/<resource>:move.

curl -X POST "http://localhost:13000/api/users:move?sourceId=1&targetId=2"

Parameters

set Copy Section

Sets associated objects for a resource. POST /api/<resource>/<resourceKey>/<association>:set.

curl "http://localhost:13000/api/users/1/roles:set" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '["admin", "member"]'

Request Body

• TargetKey | TargetKey[] - Array of primary key values for associated objects.

add Copy Section

Adds associated objects to a resource. POST /api/<resource>/<resourceKey>/<association>:add.

curl "http://localhost:13000/api/users/1/roles:add" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '["admin"]'

Request Body

• TargetKey | TargetKey[] - Array of primary key values for associated objects.

remove Copy Section

Removes associated objects from a resource. POST /api/<resource>/<resourceKey>/<association>:remove.

curl "http://localhost:13000/api/users/1/roles:remove" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '["admin"]'

Request Body

• TargetKey | TargetKey[] - Array of primary key values for associated objects.

toggle Copy Section

Toggles associated objects for a resource, adding them if they don't exist, or removing them if they do. POST /api/<resource>/<resourceKey>/<association>:toggle.

curl "http://localhost:13000/api/users/1/roles:toggle" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '["admin", "member"]'

Request Body

• TargetKey | TargetKey[] - Array of primary key values for associated objects.

File: docs/en-US/api/cli.md Copy Chapter

@nocobase/cli

The NocoBase CLI is designed to help you develop, build, and deploy NocoBase applications.

Instructions For Use Copy Chapter

$ yarn nocobase -h

Usage: nocobase [command] [options]

Options:
  -h, --help

Commands:
  console
  db:auth               Verify if the database is successfully connected
  db:sync               Generate relevant data tables and fields through the configuration of collections
  install               Install
  start                 Start application in production environment
  build                 Compile and package
  clean                 Delete the compiled files
  dev                   Start application for development environment with real-time compilation
  doc                   Documentation development
  test                  Testing
  umi
  upgrade               Upgrade
  migrator              Data migration
  pm                    Plugin manager
  help

Application in Scaffolding Copy Chapter

scripts in the application scaffolding package.json is as below:

{
  "scripts": {
    "dev": "nocobase dev",
    "start": "nocobase start",
    "clean": "nocobase clean",
    "build": "nocobase build",
    "test": "nocobase test",
    "pm": "nocobase pm",
    "postinstall": "nocobase postinstall"
  }
}

Command Line Extensions Copy Chapter

NocoBase CLI is built based on commander. You can write the extended commands freely in app/server/index.ts:

const app = new Application(config);

app.command('hello').action(() => {});

or in the plugin:

class MyPlugin extends Plugin {
  beforeLoad() {
    this.app.command('hello').action(() => {});
  }
}

Run in the terminal:

$ yarn nocobase hello

Built-in Commands Copy Chapter

Sorted by frequency of use.

`dev` Copy Section

Start application and compile code in real time in development environment.

Usage: nocobase dev [options]

Options:
  -p, --port [port]
  --client
  --server
  -h, --help

Example:

# Launch application for development environment, with real-time compilation
yarn nocobase dev
# Start the server side only
yarn nocobase dev --server
# Start the client side only
yarn nocobase dev --client

`start` Copy Section

Start application in production environment, the code needs yarn build.

$ yarn nocobase start -h

Usage: nocobase start [options]

Options:
  -p, --port
  -s, --silent
  -h, --help

Example:

# Launch application for production environment
yarn nocobase start

`install` Copy Section

Install.

$ yarn nocobase install -h

Usage: nocobase install [options]

Options:
  -f, --force
  -c, --clean
  -s, --silent
  -l, --lang [lang]
  -e, --root-email <rootEmail>
  -p, --root-password <rootPassword>
  -n, --root-nickname [rootNickname]
  -h, --help

Example:

# Initial installation
yarn nocobase install -l zh-CN -e [email protected] -p admin123
# Delete all data tables from NocoBase and reinstall
yarn nocobase install -f -l zh-CN -e [email protected] -p admin123
# Clear database and reinstall
yarn nocobase install -c -l zh-CN -e [email protected] -p admin123

`upgrade` Copy Section

Upgrade.

yarn nocobase upgrade

`test` Copy Section

jest test, which supports all jest-cli options, also supports -c, --db-clean.

$ yarn nocobase test -h

Usage: nocobase test [options]

Options:
  -c, --db-clean        Clear database before running all tests
  -h, --help

Example:

# Run all test files
yarn nocobase test
# Run all test files in the specified folder
yarn nocobase test packages/core/server
# Run all tests in the specified file
yarn nocobase test packages/core/database/src/__tests__/database.test.ts

# Clear database before running all tests
yarn nocobase test -c
yarn nocobase test packages/core/server -c

`build` Copy Section

The source code needs to be compiled and packaged before the code is deployed to the production environment; and you need to re-build the code if it has any modification.

# All packages
yarn nocobase build
# Specified packages
yarn nocobase build app/server app/client

`clean` Copy Section

Delete the compiled files.

yarn clean
# Equivalent to
yarn rimraf -rf packages/*/*/{lib,esm,es,dist}

`doc` Copy Section

Documentation development.

# Start the documentation
yarn doc  --lang=zh-CN # Equivalent to yarn doc dev
# Build the documentation, and output it to . /docs/dist/ directory by default
yarn doc build
# View the final result of the output documentation of dist
yarn doc serve --lang=zh-CN

`db:auth` Copy Section

Verify if the database is successfully connected.

$ yarn nocobase db:auth -h

Usage: nocobase db:auth [options]

Options:
  -r, --retry [retry]   Number of retries
  -h, --help

`db:sync` Copy Section

Generate relevant data tables and fields through the configuration of collections.

$ yarn nocobase db:sync -h

Usage: nocobase db:sync [options]

Options:
  -f, --force
  -h, --help   display help for command

`migrator` Copy Section

Data migration.

$ yarn nocobase migrator

Positional arguments:
  <command>
    up        Applies pending migrations
    down      Revert migrations
    pending   Lists pending migrations
    executed  Lists executed migrations
    create    Create a migration file

`pm` Copy Section

Plugin manager.

# Create plugin
yarn pm create hello
# Register plugin
yarn pm add hello
# Enable plugin
yarn pm enable hello
# Disable plugin
yarn pm disable hello
# Remove plugin
yarn pm remove hello

Not achieved yet:

# Upgrade plugin
yarn pm upgrade hello
# Publish plugin
yarn pm publish hello

`umi` Copy Section

app/client is built based on umi, you can run other relevant commands through nocobase umi.

# Generate the .umi cache needed for the development environment
yarn nocobase umi generate tmp

`help` Copy Section

The help command, you can also use the option parameter, -h and --help.

# View all cli
yarn nocobase help
# Use -h instead
yarn nocobase -h
# Or --help
yarn nocobase --help
# View options of command db:sync
yarn nocobase db:sync -h

File: docs/en-US/api/index.md Copy Chapter

Overview

File: docs/en-US/api/logger.md Copy Chapter

@nocobase/logger

Create Logger Copy Chapter

createLogger() Copy Section

Creates a custom logger.

Signature

• createLogger(options: LoggerOptions)

Type

interface LoggerOptions
  extends Omit<winston.LoggerOptions, 'transports' | 'format'> {
  dirname?: string;
  filename?: string;
  format?: 'logfmt' | 'json' | 'delimiter' | 'console' | winston.Logform.Format;
  transports?: ('console' | 'file' | 'dailyRotateFile' | winston.transport)[];
}

Details

• dirname: Log directory
• filename: Log file name
• format: Log format
• transports: Log transports

createSystemLogger() Copy Section

Creates system runtime logs printed in a specified method. Refer to Logger plugin - System log.

Signature

• createSystemLogger(options: SystemLoggerOptions)

Type

export interface SystemLoggerOptions extends LoggerOptions {
  seperateError?: boolean; // print error seperately, default true
}

Details

• seperateError: Whether to print error level logs separately

app.createLogger() Copy Section

Definition

class Application {
  createLogger(options: LoggerOptions) {
    const { dirname } = options;
    return createLogger({
      ...options,
      dirname: getLoggerFilePath(this.name || 'main', dirname || ''),
    });
  }
}

When dirname is a relative path, the log files will be output to the directory named after the current application.

plugin.createLogger() Copy Section

Usage is the same as app.createLogger().

Definition

class Plugin {
  createLogger(options: LoggerOptions) {
    return this.app.createLogger(options);
  }
}

Configuration Copy Chapter

getLoggerLevel() Copy Section

getLoggerLevel(): 'debug' | 'info' | 'warn' | 'error'

Gets the log level currently configured in the system.

getLoggerFilePath() Copy Section

getLoggerFilePath(...paths: string[]): string

Concatenates directory paths based on the log directory currently configured in the system.

getLoggerTransports() Copy Section

getLoggerTransports(): ('console' | 'file' | 'dailyRotateFile')[]

Gets the log output methods currently configured in the system.

getLoggerFormat() Copy Section

getLoggerFormat(): 'logfmt' | 'json' | 'delimiter' | 'console'

Gets the log format currently configured in the system.

Logger Transports Copy Chapter

Transports Copy Section

Predefined output methods.

• Transports.console
• Transports.file
• Transports.dailyRotateFile

import { Transports } from '@nocobase/logger';

const transport = Transports.console({
  //...
});

References Copy Chapter

• Development - Logger
• Logger Plugin

File: docs/en-US/api/acl/acl.md Copy Chapter

ACL

Overview Copy Chapter

ACL is the permission management module used in NocoBase, responsible for user role management, permission registration and authorization, as well as permission policy evaluation and access control.

Concepts Copy Section

• Resource: Collections, or custom resources can be registered. Refer to @nocobase/resourcer.
• Action: An operation interface for a resource, such as create, read, update, delete, or other custom actions. Refer to @nocobase/actions.
• Strategy: Configures global permissions for roles, such as permissions for resource operations like create, read, update, delete, import, export, and system permissions like configuring the user interface.
• Snippet: Defines a collection of operations, enabling unified management of operation permissions. Snippet identifiers can be matched using the minimatch rules.

Class Methods Copy Chapter

`define()` Copy Section

Defines a role.

Signature

• define(options: DefineOptions): ACLRole

Type Definitions

export interface DefineOptions {
  role: string;
  strategy?: string | AvailableStrategyOptions;
  actions?: ResourceActionsOptions;
  snippets?: string[];
}

export interface AvailableStrategyOptions {
  displayName?: string;
  actions?: false | string | string[];
  allowConfigure?: boolean;
  resource?: '*';
}

export interface ResourceActionsOptions {
  [actionName: string]: RoleActionParams;
}

export interface RoleActionParams {
  fields?: string[];
  filter?: any;
  own?: boolean;
  whitelist?: string[];
  blacklist?: string[];
}

Details

DefineOptions

AvailableStrategyOptions

RoleActionParams

`can()` Copy Section

Determines the permission to execute an action and returns the final action parameters. Returns null if no permission.

Signature

• can(options: CanArgs): CanResult | null

Type Definitions

interface CanArgs {
  role: string;
  resource: string;
  action: string;
  ctx?: any;
}

interface CanResult {
  role: string;
  resource: string;
  action: string;
  params?: any;
}

Details

CanArgs

CanResult

`registerSnippet()` Copy Section

Registers a snippet.

Signature

• registerSnippet(snippet: SnippetOptions)

Type Definitions

export type SnippetOptions = {
  name: string;
  actions: string[];
};

Details

`setAvailableAction()` Copy Section

Sets allowed actions.

Signature

• setAvailableAction(name: string, options: AvailableActionOptions = {})

export interface AvailableActionOptions {
  displayName?: string;
  aliases?: string[] | string;
  resource?: string;
  // Perform operations on new data
  onNewRecord?: boolean;
  // Allow configuring fields
  allowConfigureFields?: boolean;
}

Details

`setAvailableStrategy()` Copy Section

Sets allowed strategies for actions.

Signature

• setAvailableStrategy(name: string, options: AvailableStrategyOptions)

Refer to AvailableStrategyOptions.

`allow()` Copy Section

Defines the conditions under which operations are allowed.

acl.allow('plugins', '*', 'public');

Signature

• allow(resourceName: string, actionNames: string[] | string, condition?: string | ConditionFunc)

Type

export type ConditionFunc = (ctx: any) => Promise<boolean> | boolean;

Details

Predefined condition identifiers:

• public: Public interface.
• loggedIn: Allowed when the user is logged in.
• allowConfigure: Allowed when the current user role has permission to configure the user interface.

`addFixedParams()` Copy Section

Adds fixed parameters to operations, merging them with current request parameters.

acl.addFixedParams('users', 'list', () => {
  return {
    filter: {
      id: {
        $eq: 1,
      },
    },
  };
});

Signature

• addFixedParams(resource: string, action: string, merger: Merger)

Type Definitions

export type Merger = () => object;

Details

`use()` Copy Section

Adds the ACL middleware.

acl.use(async () => {
  return async function (ctx, next) {
    // ...
    await next();
  };
});

Signature

• use(fn: any, options?: ToposortOptions)

Details

Refer to Middleware.

`middleware()` Copy Section

NocoBase access control middleware.

File: docs/en-US/api/auth/auth-manager.md Copy Chapter

AuthManager

Overview Copy Chapter

AuthManager is the user authentication management module in NocoBase, used for registering different types of user authentication.

Basic Usage Copy Section

const authManager = new AuthManager({
  // Key to retrieve the current authenticator identifier from the request header
  authKey: 'X-Authenticator',
});

// Set methods for storing and retrieving authenticators in AuthManager
authManager.setStorer({
  get: async (name: string) => {
    return db.getRepository('authenticators').find({ filter: { name } });
  },
});

// Register an authentication type
authManager.registerTypes('basic', {
  auth: BasicAuth,
  title: 'Password',
});

// Use authentication middleware
app.resourceManager.use(authManager.middleware());

Concepts Copy Section

• Authentication type (AuthType): Different types of authentication, such as Password, SMS, OIDC, SAML, etc.
• Authenticator: An authenticator is a database-stored entity linked to a configuration record for a specific authentication type (AuthType). Multiple authenticators can exist for one authentication type, each offering diffrent authentications.
• Authenticator name: Unique identifier for an authenticator, used to determine the current authentication employed by the current request.

Class Methods Copy Chapter

`constructor()` Copy Section

Constructor, creates an instance of AuthManager.

Signature

• constructor(options: AuthManagerOptions)

Types

export interface JwtOptions {
  secret: string;
  expiresIn?: string;
}

export type AuthManagerOptions = {
  authKey: string;
  default?: string;
  jwt?: JwtOptions;
};

Details

AuthManagerOptions

JwtOptions

`setStorer()` Copy Section

Set methods for storing and retrieving authenticator data.

Signature

• setStorer(storer: Storer)

Types

export interface Authenticator = {
  authType: string;
  options: Record<string, any>;
  [key: string]: any;
};

export interface Storer {
  get: (name: string) => Promise<Authenticator>;
}

Details

Authenticator

Storer

Storer is the interface for authenticator storage, containing one method.

• get(name: string): Promise<Authenticator> - Get authenticator by identifier. In NocoBase, the actual returned type is AuthModel.

`registerTypes()` Copy Section

Register authentication types.

Signature

• registerTypes(authType: string, authConfig: AuthConfig)

Types

export type AuthExtend<T extends Auth> = new (config: Config) => T;

type AuthConfig = {
  auth: AuthExtend<Auth>; // The authentication class.
  title?: string; // The display name of the authentication type.
};

Details

`listTypes()` Copy Section

Get a list of registered authentication types.

Signature

• listTypes(): { name: string; title: string }[]

Details

`get()` Copy Section

Get authenticator.

Signature

• get(name: string, ctx: Context)

Details

`middleware()` Copy Section

Authentication middleware. Get the current authenticator and perform user authentication.

File: docs/en-US/api/auth/auth.md Copy Chapter

Auth

Overview Copy Chapter

Auth is an abstract class for user authentication types, defining the interfaces required to complete user authentication. To extend new user authentication types, you need to inherit from the Auth class and implement its methods. The basic implementation can be referred to as BaseAuth.

interface IAuth {
  user: Model;
  // Check the authentication status and return the current user.
  check(): Promise<Model>;
  signIn(): Promise<any>;
  signUp(): Promise<any>;
  signOut(): Promise<any>;
}

export abstract class Auth implements IAuth {
  abstract user: Model;
  abstract check(): Promise<Model>;
  // ...
}

class CustomAuth extends Auth {
  // check: Authentication
  async check() {
    // ...
  }
}

Instance Properties Copy Chapter

`user` Copy Section

Information of the authenticated user.

Signature

• abstract user: Model

Class Methods Copy Chapter

`constructor()` Copy Section

Constructor, creates an instance of Auth.

Signature

• constructor(config: AuthConfig)

Types

export type AuthConfig = {
  authenticator: Authenticator;
  options: {
    [key: string]: any;
  };
  ctx: Context;
};

Details

AuthConfig

`check()` Copy Section

User authentication, returns user information. This is an abstract method that all authentication types must implement.

Signature

• abstract check(): Promise<Model>

`signIn()` Copy Section

User login.

Signature

• signIn(): Promise<any>

`signUp()` Copy Section

User registration.

Signature

• signUp(): Promise<any>

`signOut()` Copy Section

User logout.

Signature

• signOut(): Promise<any>

File: docs/en-US/api/auth/base-auth.md Copy Chapter

BaseAuth

Overview Copy Chapter

BaseAuth inherits from the abstract class Auth and serves as the basic implementation for user authentication types, using JWT as the authentication method. In most cases, extending user authentication types can be achieved by inheriting from BaseAuth instead of directly inheriting from the Auth abstract class.

class BasicAuth extends BaseAuth {
  constructor(config: AuthConfig) {
    // Set user collection
    const userCollection = config.ctx.db.getCollection('users');
    super({ ...config, userCollection });
  }

  // User authentication logic, called by `auth.signIn`
  // Returns user data
  async validate() {
    const ctx = this.ctx;
    const { values } = ctx.action.params;
    // ...
    return user;
  }
}

Class Methods Copy Chapter

`constructor()` Copy Section

Constructor, creates an instance of BaseAuth.

Signature

• constructor(config: AuthConfig & { userCollection: Collection })

Details

`user()` Copy Section

Accessor for setting and getting user information, defaulting to using the ctx.state.currentUser object.

Signature

• set user()
• get user()

`check()` Copy Section

Authenticates through the request token and returns user information.

`signIn()` Copy Section

User login, generates a token.

`signUp()` Copy Section

User registration.

`signOut()` Copy Section

User logout, token expiration.

`validate()` \* Copy Section

Core authentication logic, called by the signIn interface, to determine whether the user can successfully log in.

File: docs/en-US/api/cache/cache-manager.md Copy Chapter

CacheManager

Overview Copy Chapter

CacheManager is based on node-cache-manager and provides caching module management for NocoBase. The built-in cache types are:

• memory: Provided by the default lru-cache of node-cache-manager.
• redis: Supported by node-cache-manager-redis-yet for Redis caching.

More types can be extended and registered through the API.

Concepts Copy Section

• Store: Defines a caching method, including a factory method for creating caches and other related configurations. Each caching method has a unique identifier provided during registration. The two built-in caching methods correspond to the unique identifiers memory and redis.

• Store Factory Method: Provided by node-cache-manager and related extension packages, used to create caches. Examples include memory provided by node-cache-manager by default, and redisStore provided by node-cache-manager-redis-yet. In this context, the object to be provided corresponds to StoreOptions, which is the first parameter of the caching method in node-cache-manager.

• Cache: A class encapsulated by NocoBase, providing methods related to cache usage. When actually using caching, operations are performed on instances of Cache. Each Cache instance has a unique identifier, which serves as a namespace for distinguishing different modules.

Class Methods Copy Chapter

`constructor()` Copy Section

Signature

• constructor(options?: CacheManagerOptions)

Type

export type CacheManagerOptions = Partial<{
  defaultStore: string;
  stores: {
    [storeType: string]: StoreOptions;
  };
}>;

type StoreOptions = {
  store?: 'memory' | FactoryStore<Store, any>;
  close?: (store: Store) => Promise<void>;
  // global config
  [key: string]: any;
};

Details

CacheManagerOptions

StoreOptions

Default `options`

import { redisStore, RedisStore } from 'cache-manager-redis-yet';

const defaultOptions: CacheManagerOptions = {
  defaultStore: 'memory',
  stores: {
    memory: {
      store: 'memory',
      // global config
      max: 2000,
    },
    redis: {
      store: redisStore,
      close: async (redis: RedisStore) => {
        await redis.client.quit();
      },
    },
  },
};

The options parameter will be merged with the default options. Existing default options can be omitted. For example:

const cacheManager = new CacheManager({
  stores: {
    defaultStore: 'redis',
    redis: {
      // redisStore is already provided in the default options, so only need to provide redisStore configuration.
      url: 'redis://localhost:6379',
    },
  },
});

`registerStore()` Copy Section

Register a new caching method. Example:

import { redisStore } from 'cache-manager-redis-yet';

cacheManager.registerStore({
  // Unique identifier for the store
  name: 'redis',
  // Factory method for creating the store
  store: redisStore,
  // Callback method for closing the store connection
  close: async (redis: RedisStore) => {
    await redis.client.quit();
  },
  // Global configurations
  url: 'xxx',
});

Signature

• registerStore(options: { name: string } & StoreOptions)

`createCache()` Copy Section

Create a cache. Example:

await cacheManager.createCache({
  name: 'default', // Unique identifier for the cache
  store: 'memory', // Unique identifier for the store
  prefix: 'mycache', // Automatically adds the 'mycache:' prefix to cache keys, optional
  // Other store configurations, custom configurations that will be merged with global store configurations
  max: 2000,
});

Signature

• createCache(options: { name: string; prefix?: string; store?: string; [key: string]: any }): Promise<Cache>

Details

options

When store is omitted, the defaultStore will be used. In this case, the caching

File: docs/en-US/api/cache/cache.md Copy Chapter

Cache

Basic Methods Copy Chapter

You can refer to the documentation of node-cache-manager.

• get()
• set()
• del()
• reset()
• wrap()
• mset()
• mget()
• mdel()
• keys()
• ttl()

Other Methods Copy Chapter

`wrapWithCondition()` Copy Section

Similar to wrap(), but can decide whether to use caching based on conditions.

async wrapWithCondition<T>(
  key: string,
  fn: () => T | Promise<T>,
  options?: {
    // External parameter to control whether to use cache results
    useCache?: boolean;
    // Determine whether to cache based on data results
    isCacheable?: (val: unknown) => boolean | Promise<boolean>;
    ttl?: Milliseconds;
  },
): Promise<T> {

`setValueInObject()` Copy Section

When the cached content is an object, changes the value of a specific key.

async setValueInObject(key: string, objectKey: string, value: unknown)

`getValueInObject()` Copy Section

When the cached content is an object, retrieves the value of a specific key.

async getValueInObject(key: string, objectKey: string)

`delValueInObject()` Copy Section

When the cached content is an object, deletes a specific key.

async delValueInObject(key: string, objectKey: string)

File: docs/en-US/api/client/application.md Copy Chapter

Application

Constructor Copy Chapter

`constructor()` Copy Section

Create an application instance.

Signature

• constructor(options: ApplicationOptions)

Example

const app = new Application({
  apiClient: {
    baseURL: process.env.API_BASE_URL,
  },
  dynamicImport: (name: string) => {
    return import(`../plugins/${name}`);
  },
});

Methods Copy Chapter

use() Copy Section

Add Providers, build-in Providers are:

• APIClientProvider
• I18nextProvider
• AntdConfigProvider
• SystemSettingsProvider
• PluginManagerProvider
• SchemaComponentProvider
• SchemaInitializerProvider
• BlockSchemaComponentProvider
• AntdSchemaComponentProvider
• ACLProvider
• RemoteDocumentTitleProvider

render() Copy Section

Component to render the App.

import { Application } from '@nocobase/client';

export const app = new Application({
  apiClient: {
    baseURL: process.env.API_BASE_URL,
  },
  dynamicImport: (name: string) => {
    return import(`../plugins/${name}`);
  },
});

export default app.render();

File: docs/en-US/api/client/index.md Copy Chapter

Overview

test

File: docs/en-US/api/client/router.md Copy Chapter

Router

API Copy Chapter

Initial Copy Section

const app = new Application({
  router: {
    type: 'browser', // type default value is `browser`
  },
});

// or
const app = new Application({
  router: {
    type: 'memory',
    initialEntries: ['/'],
  },
});

add Route Copy Section

basic

import { RouteObject } from 'react-router-dom';
const app = new Application();

const Hello = () => {
  return <div>Hello</div>;
};

// first argument is `name` of route, second argument is `RouteObject`
app.router.add('root', {
  path: '/',
  element: <Hello />,
});

app.router.add('root', {
  path: '/',
  Component: Hello,
});

Component is String

app.addComponents({
  Hello,
});
app.router.add('root', {
  path: '/',
  Component: 'Hello',
});

nested

import { Outlet } from 'react-router-dom';

const Layout = () => {
  return (
    <div>
      <Link to="/home">Home</Link>
      <Link to="/about">about</Link>

      <Outlet />
    </div>
  );
};

const Home = () => {
  return <div>Home</div>;
};

const About = () => {
  return <div>About</div>;
};

app.router.add('root', {
  element: <Layout />,
});
app.router.add('root.home', {
  path: '/home',
  element: <Home />,
});
app.router.add('root.about', {
  path: '/about',
  element: <About />,
});

It will generate the following routes:

{
  element: <Layout />,
  children: [
    {
      path: '/home',
      element: <Home />
    },
    {
      path: '/about',
      element: <About />
    }
  ]
}

remove Route Copy Section

// remove route by name
app.router.remove('root.home');
app.router.remove('hello');

Router in plugin

class MyPlugin extends Plugin {
  async load() {
    // add route
    this.app.router.add('hello', {
      path: '/hello',
      element: <div>hello</div>,
    });

    // remove route
    this.app.router.remove('world');
  }
}

Example Copy Chapter

/**
 * defaultShowCode: true
 */
import React from 'react';
import { Link, Outlet } from 'react-router-dom';
import { Application } from '@nocobase/client';

const Home = () => <h1>Home</h1>;
const About = () => <h1>About</h1>;

const Layout = () => {
  return (
    <div>
      <div>
        <Link to={'/'}>Home</Link>, <Link to={'/about'}>About</Link>
      </div>
      <Outlet />
    </div>
  );
};

const app = new Application({
  router: {
    type: 'memory',
    initialEntries: ['/'],
  },
});

app.router.add('root', {
  element: <Layout />,
});

app.router.add('root.home', {
  path: '/',
  element: <Home />,
});

app.router.add('root.about', {
  path: '/about',
  element: <About />,
});

export default app.getRootComponent();

File: docs/en-US/api/client/extensions/acl.md Copy Chapter

ACL

Components Copy Chapter

`` Copy Section

`` Copy Section

`` Copy Section

`` Copy Section

`` Copy Section

`` Copy Section

Hooks Copy Chapter

`useACLContext()` Copy Section

`useACLRoleContext()` Copy Section

`useRoleRecheck()` Copy Section

File: docs/en-US/api/client/extensions/block-provider.md Copy Chapter

BlockProvider

Kernel Methods Copy Chapter

`` Copy Section

`useBlockRequestContext()` Copy Section

Build-in BlockProvider Components Copy Chapter

`` Copy Section

`` Copy Section

`` Copy Section

`` Copy Section

`` Copy Section

`` Copy Section

`` Copy Section

`` Copy Section

File: docs/en-US/api/client/extensions/collection-manager.md Copy Chapter

CollectionManager

Components Copy Chapter

CollectionManagerProvider Copy Section

<CollectionManagerProvider
  interfaces={{}}
  collections={[]}
></CollectionManagerProvider>

CollectionProvider Copy Section

const collection = {
  name: 'tests',
  fields: [
    {
      type: 'string',
      name: 'title',
      interface: 'input',
      uiSchema: {
        type: 'string',
        'x-component': 'Input',
      },
    },
  ],
};
<CollectionProvider collection={collection}></CollectionProvider>;

If there is no collection parameter passed in, get the collection from CollectionManagerProvider with the corresponding name.

const collections = [
  {
    name: 'tests',
    fields: [
      {
        type: 'string',
        name: 'title',
        interface: 'input',
        uiSchema: {
          type: 'string',
          'x-component': 'Input',
        },
      },
    ],
  },
];
<CollectionManagerProvider collections={collections}>
  <CollectionProvider name={'tests'}></CollectionProvider>
</CollectionManagerProvider>;

CollectionFieldProvider Copy Section

const field = {
  type: 'string',
  name: 'title',
  interface: 'input',
  uiSchema: {
    type: 'string',
    'x-component': 'Input',
  },
};
<CollectionFieldProvider field={field}></CollectionFieldProvider>;

If there is no field parameter passed in, get the field from CollectionProvider with the corresponding name.

const collection = {
  name: 'tests',
  fields: [
    {
      type: 'string',
      name: 'title',
      interface: 'input',
      uiSchema: {
        type: 'string',
        'x-component': 'Input',
      },
    },
  ],
};
<CollectionProvider collection={collection}>
  <CollectionFieldProvider name={'title'}></CollectionFieldProvider>
</CollectionProvider>;

CollectionField Copy Section

Universal field component that needs to be used with <CollectionProvider/>, but only in schema scenarios. Get the field schema from CollectionProvider with the corresponding name. Extend the configuration via the schema where the CollectionField is located.

{
  name: 'title',
  'x-decorator': 'FormItem',
  'x-decorator-props': {},
  'x-component': 'CollectionField',
  'x-component-props': {},
  properties: {},
}

Hooks Copy Chapter

useCollectionManager() Copy Section

Use with <CollectionManagerProvider/>.

const { collections, get } = useCollectionManager();

useCollection() Copy Section

Use with <CollectionProvider/>.

const { name, fields, getField, findField, resource } = useCollection();

useCollectionField() Copy Section

Use with <CollectionFieldProvider/>.

const { name, uiSchema, resource } = useCollectionField();

The resource needs to be used with <RecordProvider/> to provide context of the record of the current data table row.

CollectionManager

Components Copy Chapter

CollectionManagerProvider Copy Section

<CollectionManagerProvider
  interfaces={{}}
  collections={[]}
></CollectionManagerProvider>

CollectionProvider Copy Section

const collection = {
  name: 'tests',
  fields: [
    {
      type: 'string',
      name: 'title',
      interface: 'input',
      uiSchema: {
        type: 'string',
        'x-component': 'Input',
      },
    },
  ],
};
<CollectionProvider collection={collection}></CollectionProvider>;

If there is no collection parameter passed in, get the collection from CollectionManagerProvider with the corresponding name.

const collections = [
  {
    name: 'tests',
    fields: [
      {
        type: 'string',
        name: 'title',
        interface: 'input',
        uiSchema: {
          type: 'string',
          'x-component': 'Input',
        },
      },
    ],
  },
];
<CollectionManagerProvider collections={collections}>
  <CollectionProvider name={'tests'}></CollectionProvider>
</CollectionManagerProvider>;

CollectionFieldProvider Copy Section

const field = {
  type: 'string',
  name: 'title',
  interface: 'input',
  uiSchema: {
    type: 'string',
    'x-component': 'Input',
  },
};
<CollectionFieldProvider field={field}></CollectionFieldProvider>;

If there is no field parameter passed in, get the field from CollectionProvider with the corresponding name.

const collection = {
  name: 'tests',
  fields: [
    {
      type: 'string',
      name: 'title',
      interface: 'input',
      uiSchema: {
        type: 'string',
        'x-component': 'Input',
      },
    },
  ],
};
<CollectionProvider collection={collection}>
  <CollectionFieldProvider name={'title'}></CollectionFieldProvider>
</CollectionProvider>;

CollectionField Copy Section

Universal field component that needs to be used with <CollectionProvider/>, but only in schema scenarios. Get the field schema from CollectionProvider with the corresponding name. Extend the configuration via the schema where the CollectionField is located.

{
  name: 'title',
  'x-decorator': 'FormItem',
  'x-decorator-props': {},
  'x-component': 'CollectionField',
  'x-component-props': {},
  properties: {},
}

Hooks Copy Chapter

useCollectionManager() Copy Section

Use with <CollectionManagerProvider/>.

const { collections, get } = useCollectionManager();

useCollection() Copy Section

Use with <CollectionProvider/>.

const { name, fields, getField, findField, resource } = useCollection();

useCollectionField() Copy Section

Use with <CollectionFieldProvider/>.

const { name, uiSchema, resource } = useCollectionField();

The resource needs to be used with <RecordProvider/> to provide context of the record of the current data table row.

File: docs/en-US/api/client/extensions/schema-component.md Copy Chapter

适配的 Schema 组件

Common Copy Chapter

• DndContext
• SortableItem

And Design Copy Chapter

• Action
• BlockItem
• Calendar
• CardItem
• Cascader

File: docs/en-US/api/client/schema-designer/schema-component.md Copy Chapter

SchemaComponent

Core Components Copy Chapter

`` Copy Section

`` Copy Section

`` Copy Section

Core Methods Copy Chapter

`createDesignable()` Copy Section

`useDesignable()` Copy Section

`useCompile()` Copy Section

File: docs/en-US/api/client/schema-designer/schema-initializer.md Copy Chapter

SchemaInitializer

Used for the initialization of various schemas. Newly added schema can be inserted anywhere in an existing schema node, including:

{
  properties: {
    // beforeBegin - Insert in front of the current node
    node1: {
      properties: {
        // afterBegin - Insert in front of the first child node of the current node
        // ...
        // beforeEnd - After the last child node of the current node
      },
    },
    // afterEnd - After the current node
  },
}

The core of SchemaInitializer includes <SchemaInitializer.Button /> and <SchemaInitializer.Item /> the two components. <SchemaInitializer.Button /> is used to create the dropdown menu button of schema, and the options of the dropdown menu is <SchemaInitializer.Item/>.

`` Copy Section

`` Copy Section

`` Copy Section

File: docs/en-US/api/client/schema-designer/schema-settings.md Copy Chapter

SchemaSettings

`` Copy Section

`` Copy Section

`` Copy Section

`` Copy Section

`` Copy Section

`` Copy Section

`` Copy Section

`` Copy Section

`` Copy Section

`` Copy Section

`` Copy Section

`` Copy Section

File: docs/en-US/api/data-source-manager/data-source.md Copy Chapter

DataSource (abstract)

The DataSource abstract class is used to represent a type of data source, which can be a database, API, etc.

Members Copy Chapter

collectionManager Copy Section

The CollectionManager instance of the data source, which needs to implement the ICollectionManager interface.

resourceManager Copy Section

The resourceManager instance of the data source, see: resourceManager

acl Copy Section

The ACL instance of the data source, see: ACL

API Copy Chapter

constructor() Copy Section

Constructor, creates a DataSource instance.

Signature

• constructor(options: DataSourceOptions)

init() Copy Section

Initialization function, called immediately after constructor.

Signature

• init(options: DataSourceOptions)

name Copy Section

Signature

• get name()

Returns the instance name of the data source.

middleware() Copy Section

Gets the middleware of the DataSource, used to mount to the Server to receive requests.

testConnection() Copy Section

Static method, called during the test connection operation, can be used for parameter validation, specific logic is implemented by subclasses.

Signature

• static testConnection(options?: any): Promise

load() Copy Section

Signature

• async load(options: any = {})

The loading operation of the data source, logic is implemented by subclasses.

createCollectionManager() Copy Section

Signature

• abstract createCollectionManager(options?: any): ICollectionManager

Creates a CollectionManager instance for the data source, logic is implemented by subclasses.

createResourceManager() Copy Section

Creates a ResourceManager instance for the data source, subclasses can override the implementation, by default creates ResourceManager from @nocobase/resourcer.

createACL() Copy Section

• Creates an ACL instance for the DataSource, subclasses can override the implementation, by default creates ACL from @nocobase/acl.

File: docs/en-US/api/data-source-manager/i-collection-manager.md Copy Chapter

ICollectionManager

The ICollectionManager interface is used to manage Collection instances of data sources.

API Copy Chapter

registerFieldTypes() Copy Section

Registers the field types in a Collection.

Signature

• registerFieldTypes(types: Record<string, any>): void

registerFieldInterfaces() Copy Section

Registers the Interface for a Collection.

Signature

• registerFieldInterfaces(interfaces: Record<string, any>): void

registerCollectionTemplates() Copy Section

Registers Collection Templates.

Signature

• registerCollectionTemplates(templates: Record<string, any>): void

registerModels() Copy Section

Registers Models.

Signature

• registerModels(models: Record<string, any>): void

registerRepositories() Copy Section

Registers Repositories.

Signature

• registerRepositories(repositories: Record<string, any>): void

getRegisteredRepository() Copy Section

Retrieves an instance of a registered repository.

Signature

• getRegisteredRepository(key: string): IRepository

defineCollection() Copy Section

Defines a Collection.

Signature

• defineCollection(options: CollectionOptions): ICollection

extendCollection() Copy Section

Modifies an existing Collection property.

Signature

• extendCollection(collectionOptions: CollectionOptions, mergeOptions?: MergeOptions): ICollection

hasCollection() Copy Section

Determines if a Collection exists.

Signature

• hasCollection(name: string): boolean

getCollection() Copy Section

Retrieves an instance of a Collection.

Signature

• getCollection(name: string): ICollection

getCollections() Copy Section

Retrieves all instances of Collection.

Signature

• getCollections(): Array

getRepository() Copy Section

Retrieves an instance of a Repository.

Signature

• getRepository(name: string, sourceId?: string | number): IRepository

sync() Copy Section

Synchronizes the data source, with the logic implemented by subclasses.

Signature

• sync(): Promise<void>

File: docs/en-US/api/data-source-manager/i-collection.md Copy Chapter

ICollection

ICollection is an interface for data models, which includes information such as the model's name, fields, associations, etc.

export interface ICollection {
  repository: IRepository;

  updateOptions(options: any): void;

  setField(name: string, options: any): IField;

  removeField(name: string): void;

  getFields(): Array<IField>;

  getField(name: string): IField;

  [key: string]: any;
}

Members Copy Chapter

repository Copy Section

The Repository instance to which ICollection belongs.

API Copy Chapter

updateOptions() Copy Section

Updates the properties of the Collection.

Signature

• updateOptions(options: any): void

setField() Copy Section

Sets a field of the Collection.

Signature

• setField(name: string, options: any): IField

removeField() Copy Section

Removes a field from the Collection.

Signature

• removeField(name: string): void

getFields() Copy Section

Retrieves all fields of the Collection.

Signature

• getFields(): Array

getField() Copy Section

Retrieves a field of the Collection by name.

Signature

• getField(name: string): IField

File: docs/en-US/api/data-source-manager/i-field.md Copy Chapter

IField

IField defines the interface that fields need to implement.

export type FieldOptions = {
  name: string;
  field: string;
  rawType: string;
  type: string;
  description?: string;
  interface?: string;
  uiSchema?: any;
  possibleTypes?: string[];
  defaultValue?: any;
  primaryKey: boolean;
  unique: boolean;
  allowNull?: boolean;
  autoIncrement?: boolean;
  [key: string]: any;
};

export interface IField {
  options: FieldOptions;
}

Properties Copy Chapter

options Copy Section

• Type: FieldOptions

File: docs/en-US/api/data-source-manager/i-model.md Copy Chapter

IModel

The IModel interface defines the basic properties and methods of a model object.

export interface IModel {
  toJSON: () => any;
}

API Copy Chapter

toJSON() Copy Section

Converts the model object to JSON format.

File: docs/en-US/api/data-source-manager/i-repository.md Copy Chapter

IRepository

The Repository interface defines a series of model operation methods for adapting CRUD (Create, Read, Update, Delete) operations on data sources.

API Copy Chapter

find() Copy Section

Returns a list of models that match the query parameters.

Signature

• find(options?: any): Promise

findOne() Copy Section

Returns the first model that matches the query parameters. If multiple models match, only the first one is returned.

Signature

• findOne(options?: any): Promise

count() Copy Section

Returns the number of models that match the query parameters.

Signature

• count(options?: any): Promise<Number>

findAndCount() Copy Section

Returns both the list of models and the count of models that match the query parameters.

Signature

• findAndCount(options?: any): Promise<[IModel[], Number]>

create() Copy Section

Creates a model data object.

Signature

• create(options: any): void

update() Copy Section

Updates the model data object based on the query conditions.

Signature

• update(options: any): void

destroy() Copy Section

Deletes the model data object based on the query conditions.

Signature

• destroy(options: any): void

File: docs/en-US/api/data-source-manager/index.md Copy Chapter

DataSourceManager

DataSourceManager is a management class for multiple dataSource instances.

API Copy Chapter

add() Copy Section

Adds a dataSource instance.

Signature

• add(dataSource: DataSource, options: any = {}): Promise<void>

use() Copy Section

Adds a global middleware to the dataSource instance.

middleware() Copy Section

Retrieves the middleware of the current dataSourceManager instance, which can be used to respond to HTTP requests.

afterAddDataSource() Copy Section

A hook function that is triggered after a new dataSource is added.

Signature

• afterAddDataSource(hook: DataSourceHook)

type DataSourceHook = (dataSource: DataSource) => void;

registerDataSourceType() Copy Section

Registers the data source type and its class.

Signature

• registerDataSourceType(type: string, dataSourceClass: typeof DataSource)

getDataSourceType() Copy Section

Retrieves the data source class.

Signature

• getDataSourceType(type: string): typeof DataSource

buildDataSourceByType() Copy Section

Creates a data source instance based on the registered data source type and instance parameters.

Signature

• buildDataSourceByType(type: string, options: any): DataSource

File: docs/en-US/api/database/collection.md Copy Chapter

Collection

Overview Copy Chapter

Collection is used to define the data model in the system, such as model name, fields, indexes, associations, and other information. It is usually called through the collection method of the Database instance as a proxy entry.

const { Database } = require('@nocobase/database')

// Create database instance
const db = new Database({...});

// Define data model
db.collection({
  name: 'users',
  // Define model fields
  fields: [
    // Scalar field
    {
      name: 'name',
      type: 'string',
    },

    // Association field
    {
      name: 'profile',
      type: 'hasOne' // 'hasMany', 'belongsTo', 'belongsToMany'
    }
  ],
});

Refer to Fields for more field types.

Constructor Copy Chapter

Signature

• constructor(options: CollectionOptions, context: CollectionContext)

Parameter

Example

Create a table posts:

const posts = new Collection(
  {
    name: 'posts',
    fields: [
      {
        type: 'string',
        name: 'title',
      },
      {
        type: 'double',
        name: 'price',
      },
    ],
  },
  {
    // An existing database instance
    database: db,
  },
);

Instance Members Copy Chapter

`options` Copy Section

Initial parameters for data table configuration, which are consistent with the options parameter of the constructor.

`context` Copy Section

The contextual environment to which the current data table belongs, currently mainly the database instance.

`name` Copy Section

Name of the data table.

`db` Copy Section

The database instance to which it belongs.

`filterTargetKey` Copy Section

Name of the field that is used as the primary key.

`isThrough` Copy Section

Whether it is an intermediate table.

`model` Copy Section

Match the Model type of Sequelize.

`repository` Copy Section

Data repository instance.

Field Configuration Methods Copy Chapter

`getField()` Copy Section

Get a field object whose corresponding name has been defined in the data table.

Signature

• getField(name: string): Field

Parameter

Example

const posts = db.collection({
  name: 'posts',
  fields: [
    {
      type: 'string',
      name: 'title',
    },
  ],
});

const field = posts.getField('title');

`setField()` Copy Section

Set a field to the data table.

Signature

• setField(name: string, options: FieldOptions): Field

Parameter

Example

const posts = db.collection({ name: 'posts' });

posts.setField('title', { type: 'string' });

`setFields()` Copy Section

Set multiple fields to the data table.

Signature

• setFields(fields: FieldOptions[], resetFields = true): Field[]

Parameter

Example

const posts = db.collection({ name: 'posts' });

posts.setFields([
  { type: 'string', name: 'title' },
  { type: 'double', name: 'price' },
]);

`removeField()` Copy Section

Remove a field object whose corresponding name has been defined in the data table.

Signature

• removeField(name: string): void | Field

Parameter

Example

const posts = db.collection({
  name: 'posts',
  fields: [
    {
      type: 'string',
      name: 'title',
    },
  ],
});

posts.removeField('title');

`resetFields()` Copy Section

Reset (Empty) fields of the data table.

Signature

• resetFields(): void

Example

const posts = db.collection({
  name: 'posts',
  fields: [
    {
      type: 'string',
      name: 'title',
    },
  ],
});

posts.resetFields();

`hasField()` Copy Section

Check if the data table has defined a field object with the corresponding name.

Signature

• hasField(name: string): boolean

Parameter

Example

const posts = db.collection({
  name: 'posts',
  fields: [
    {
      type: 'string',
      name: 'title',
    },
  ],
});

posts.hasField('title'); // true

`findField()` Copy Section

Find field objects in the data table that match the conditions.

Signature

• findField(predicate: (field: Field) => boolean): Field | undefined

Parameter

Example

const posts = db.collection({
  name: 'posts',
  fields: [
    {
      type: 'string',
      name: 'title',
    },
  ],
});

posts.findField((field) => field.name === 'title');

`forEachField()` Copy Section

Iterate over field objects in the data table.

Signature

• forEachField(callback: (field: Field) => void): void

Parameter

Example

const posts = db.collection({
  name: 'posts',
  fields: [
    {
      type: 'string',
      name: 'title',
    },
  ],
});

posts.forEachField((field) => console.log(field.name));

Index Configuration Methods Copy Chapter

`addIndex()` Copy Section

Add data table index.

Signature

• addIndex(index: string | string[] | { fields: string[], unique?: boolean,[key: string]: any })

Parameter

Example

const posts = db.collection({
  name: 'posts',
  fields: [
    {
      type: 'string',
      name: 'title',
    },
  ],
});

posts.addIndex({
  fields: ['title'],
  unique: true,
});

`removeIndex()` Copy Section

Remove data table index.

Signature

• removeIndex(fields: string[])

Parameter

Example

const posts = db.collection({
  name: 'posts',
  fields: [
    {
      type: 'string',
      name: 'title',
    },
  ],
  indexes: [
    {
      fields: ['title'],
      unique: true,
    },
  ],
});

posts.removeIndex(['title']);

Table Configuration Methods Copy Chapter

`remove()` Copy Section

Remove data table.

Signature

• remove(): void

Example

const posts = db.collection({
  name: 'posts',
  fields: [
    {
      type: 'string',
      name: 'title',
    },
  ],
});

posts.remove();

Database Operation Methods Copy Chapter

`sync()` Copy Section

Synchronize the definitions in data table to the database. In addition to the default Model.sync logic in Sequelize, the data tables corresponding to the relational fields will also be handled together.

Signature

• sync(): Promise<void>

Example

const posts = db.collection({
  name: 'posts',
  fields: [
    {
      type: 'string',
      name: 'title',
    },
  ],
});

await posts.sync();

`existsInDb()` Copy Section

Check whether the data table exists in the database.

Signature

• existsInDb(options?: Transactionable): Promise

Parameter

Example

const posts = db.collection({
  name: 'posts',
  fields: [
    {
      type: 'string',
      name: 'title',
    },
  ],
});

const existed = await posts.existsInDb();

console.log(existed); // false

`removeFromDb()` Copy Section

Signature

• removeFromDb(): Promise<void>

Example

const books = db.collection({
  name: 'books',
});

//  Synchronize the table books to the database
await db.sync();

// Remove the table books from the database
await books.removeFromDb();

File: docs/en-US/api/database/field.md Copy Chapter

Field

Overview Copy Chapter

Data table field management class (abstract class). It is also the base class for all field types, and any other field types are implemented by inheriting from this class.

Refer to Extended Field Types to see how to customize fields.

Constructor Copy Chapter

It is usually not called directly by the developer, but mainly through the db.collection({ fields: [] }) method as a proxy entry.

Extended field is implemented mainly by inheriting the Field abstract class and registering it to a Database instance.

Signature

• constructor(options: FieldOptions, context: FieldContext)

Parameter

Instance Members Copy Chapter

`name` Copy Section

Field name.

`type` Copy Section

Field type.

`dataType` Copy Section

Data type of the field.

`options` Copy Section

Configuration parameters to initialize the field.

`context` Copy Section

Field context object.

Configuration Methods Copy Chapter

`on()` Copy Section

Quick definition method based on data table events. It is equivalent to db.on(this.collection.name + '.' + eventName, listener).

It is usually not necessary to override this method when inheriting.

Signature

• on(eventName: string, listener: (...args: any[]) => void)

Parameter

`off()` Copy Section

Quick removal method based on data table events. It is equivalent to db.off(this.collection.name + '.' + eventName, listener).

It is usually not necessary to override this method when inheriting.

Signature

• off(eventName: string, listener: (...args: any[]) => void)

Parameter

`bind()` Copy Section

The execution content that is triggered when a field is added to data table. Typically used to add data table event listeners and other processing.

The corresponding super.bind() method needs to be called first when inheriting.

Signature

• bind()

`unbind()` Copy Section

The execution content that is triggered when a field is removed from data table. Typically used to remove data table event listeners and other processing.

The corresponding super.unbind() method needs to be called first when inheriting.

Signature

• unbind()

`get()` Copy Section

Get the values of a configuration item of the field.

Signature

• get(key: string): any

Parameter

Example

const field = db.collection('users').getField('name');

// Get and return the values of the configuration item 'name'
console.log(field.get('name'));

`merge()` Copy Section

Merge the values of a configuration item of the field.

Signature

• merge(options: { [key: string]: any }): void

Parameter

Example

const field = db.collection('users').getField('name');

field.merge({
  // Add an index configuration
  index: true,
});

`remove()` Copy Section

Remove a field from data table (from memory only).

Example

const books = db.getCollections('books');

books.getField('isbn').remove();

// really remove from db
await books.sync();

Database Methods Copy Chapter

`removeFromDb()` Copy Section

Remove a field from the database.

Signature

• removeFromDb(options?: Transactionable): Promise<void>

Parameter

`existsInDb()` Copy Section

Check if a field exists in the database.

Signature

• existsInDb(options?: Transactionable): Promise

Parameter

Built-in Field Types Copy Chapter

NocoBase has some built-in common field types, the corresponding type name can be used directly to specify the type of field upon definition. Fields of different types are configured differently, please refer to the list below.

The configuration items of all field types are passed through to Sequelize in addition to those described below. Therefore, all field configuration items supported by Sequelize can be used here (e.g. allowNull, defaultValue, etc.).

Moreover, server-side field types are mainly used for solving the problems of database storage and some algorithms, they are barely relevant to the field display types and the use of components in front-end. The front-end field types can be found in the corresponding tutorials.

`'boolean'` Copy Section

Boolean type.

Example

db.collection({
  name: 'books',
  fields: [
    {
      type: 'boolean',
      name: 'published',
    },
  ],
});

`'integer'` Copy Section

Integer type (32 bits).

Example

db.collection({
  name: 'books',
  fields: [
    {
      type: 'integer',
      name: 'pages',
    },
  ],
});

`'bigInt'` Copy Section

Long integer type (64 bits).

Example

db.collection({
  name: 'books',
  fields: [
    {
      type: 'bigInt',
      name: 'words',
    },
  ],
});

`'double'` Copy Section

Double-precision floating-point format (64 bits).

Example

db.collection({
  name: 'books',
  fields: [
    {
      type: 'double',
      name: 'price',
    },
  ],
});

`'real'` Copy Section

Real type (PG only).

`'decimal'` Copy Section

Decimal type.

`'string'` Copy Section

String type. Equivalent to the VARCHAR type for most databases.

Example

db.collection({
  name: 'books',
  fields: [
    {
      type: 'string',
      name: 'title',
    },
  ],
});

`'text'` Copy Section

Text type. Equivalent to the TEXT type for most databases.

Example

db.collection({
  name: 'books',
  fields: [
    {
      type: 'text',
      name: 'content',
    },
  ],
});

`'password'` Copy Section

Password type (NocoBase extension). Password encryption based on the scrypt method of Node.js native crypto packages.

Example

db.collection({
  name: 'users',
  fields: [
    {
      type: 'password',
      name: 'password',
      length: 64, // Length, default is 64
      randomBytesSize: 8, // Length of random bytes, default is 8
    },
  ],
});

Parameter

`'date'` Copy Section

Date type.

`'time'` Copy Section

Time type.

`'array'` Copy Section

Array type (PG only).

`'json'` Copy Section

JSON type.

`'jsonb'` Copy Section

JSONB type (PG only, others will be compatible with the 'json' type).

`'uuid'` Copy Section

UUID type.

`'uid'` Copy Section

UID type (NocoBase extension). Short random string identifier type.

`'formula'` Copy Section

Formula type (NocoBase extension). Mathematical formula calculation can be configured based on mathjs, and the formula can refer to the values of other columns in the same record to participate in the calculation.

Example

db.collection({
  name: 'orders',
  fields: [
    {
      type: 'double',
      name: 'price',
    },
    {
      type: 'integer',
      name: 'quantity',
    },
    {
      type: 'formula',
      name: 'total',
      expression: 'price * quantity',
    },
  ],
});

`'radio'` Copy Section

Radio type (NocoBase extension). The field value is 'true' for at most one row of data for the full table, all others are 'false' or 'null'.

Example

There is only one user marked as root in the entire system, once the root value of any other user is changed to true, all other records with root of true will be changed to false:

db.collection({
  name: 'users',
  fields: [
    {
      type: 'radio',
      name: 'root',
    },
  ],
});

`'sort'` Copy Section

Sorting type (NocoBase extension). Sorting based on integer numbers, automatically generating new serial numbers for new records, and rearranging serial numbers when moving data.

If data table has the sortable option defined, the corresponding fields will be generated automatically.

Example

Posts are sortable based on the users they belong to.

db.collection({
  name: 'posts',
  fields: [
    {
      type: 'belongsTo',
      name: 'user',
    },
    {
      type: 'sort',
      name: 'priority',
      scopeKey: 'userId', // Sort data grouped by the values of userId
    },
  ],
});

`'virtual'` Copy Section

Virtual type. No Data is actually stored, it is used only when special getter/setter is defined.

`'belongsTo'` Copy Section

Many-to-one association type. Foreign key is stored in its own table, as opposed to 'hasOne'/'hasMany'.

Example

Any post belongs to an author:

db.collection({
  name: 'posts',
  fields: [
    {
      type: 'belongsTo',
      name: 'author',
      target: 'users', // Default table name is the plural form of <name>
      foreignKey: 'authorId', // Default is '<name> + Id'
      sourceKey: 'id', // Default is id of the <target> table
    },
  ],
});

`'hasOne'` Copy Section

One-to-one association type. Foreign key is stored in the association table, as opposed to 'belongsTo'.

Example

Any user has a profile:

db.collection({
  name: 'users',
  fields: [
    {
      type: 'hasOne',
      name: 'profile',
      target: 'profiles', // Can be omitted
    },
  ],
});

`'hasMany'` Copy Section

One-to-many association type. The foreign key is stored in the association table, as opposed to 'belongsTo'.

Example

Any user can have multiple posts:

db.collection({
  name: 'users',
  fields: [
    {
      type: 'hasMany',
      name: 'posts',
      foreignKey: 'authorId',
      sourceKey: 'id',
    },
  ],
});

`'belongsToMany'` Copy Section

Many-to-many association type. Intermediate table is used to store both foreign keys. If no existing table is specified as intermediate table, it will be created automatically.

Example

Any post can have multiple tags added to it, and any tag can be added to multiple posts:

db.collection({
  name: 'posts',
  fields: [
    {
      type: 'belongsToMany',
      name: 'tags',
      target: 'tags', // Can be omitted if name is the same
      through: 'postsTags', // Intermediate table will be generated automatically if not specified
      foreignKey: 'postId', // Foreign key in the intermediate table referring to the table itself
      sourceKey: 'id', // Primary key of the table itself
      otherKey: 'tagId', // Foreign key in the intermediate table referring to the association table
    },
  ],
});

db.collection({
  name: 'tags',
  fields: [
    {
      type: 'belongsToMany',
      name: 'posts',
      through: 'postsTags', // Refer to the same intermediate table in the same set of relation
    },
  ],
});

File: docs/en-US/api/database/index.md Copy Chapter

Database

Overview Copy Chapter

Database is the database interaction tool provided by NocoBase, it provides very convenient database interaction features for no-code and low-code applications. The supported databases are:

• SQLite 3.8.8+
• MySQL 8.0.17+
• PostgreSQL 10.0+

Connect to Database Copy Section

In Database constructor, database connection can be configured by passing the options parameter.

const { Database } = require('@nocobase/database');

// MySQL database configuration parameters
const database = new Database({
  dialect: 'mysql',
  host: 'localhost',
  port: 3306,
  database: 'nocobase',
  username: 'root',
  password: 'password'
})

// MySQL \ PostgreSQL database configuration parameters
const database = new Database({
  dialect: /* 'postgres' or 'mysql' */,
  database: 'database',
  username: 'username',
  password: 'password',
  host: 'localhost',
  port: 'port'
})

Refer to Constructor for detailed configurations.

Define Data Structure Copy Section

Database defines database structure through Collection, one Collection object represents one table in the database.

// Define Collection
const UserCollection = database.collection({
  name: 'users',
  fields: [
    {
      name: 'name',
      type: 'string',
    },
    {
      name: 'age',
      type: 'integer',
    },
  ],
});

After the database structure is defined, use sync() method to synchronize the database structure.

await database.sync();

Refer to Collection for detailed usage of Collection.

CRUD Data Copy Section

Database operates data through Repository.

const UserRepository = UserCollection.repository();

// Create
await UserRepository.create({
  name: 'Mark',
  age: 18,
});

// Query
const user = await UserRepository.findOne({
  filter: {
    name: 'Mark',
  },
});

// Update
await UserRepository.update({
  values: {
    age: 20,
  },
});

// Delete
await UserRepository.destroy(user.id);

Refer to Repository for details of data CRUD.

Constructor Copy Chapter

Signature

• constructor(options: DatabaseOptions)

Create a database instance.

Parameter

Migration Methods Copy Chapter

`addMigration()` Copy Section

Add single migration file.

Signature

• addMigration(options: MigrationItem)

Parameter

Example

db.addMigration({
  name: '20220916120411-test-1',
  async up() {
    const queryInterface = this.context.db.sequelize.getQueryInterface();
    await queryInterface.query(/* your migration sqls */);
  },
});

`addMigrations()` Copy Section

Add the migration files in the specified directory.

Signature

• addMigrations(options: AddMigrationsOptions): void

Parameter

Example

db.addMigrations({
  directory: path.resolve(__dirname, './migrations'),
  namespace: 'test',
});

Tool Methods Copy Chapter

`inDialect()` Copy Section

Check whether the current database type is the specified type.

Signature

• inDialect(dialect: string[]): boolean

Parameter

`getTablePrefix()` Copy Section

Get the table name prefix in the configuration.

Signature

• getTablePrefix(): string

Data Table Configurations Copy Chapter

`collection()` Copy Section

Define a data table. This is like the define method of Sequelize, which only creates table structure in memory. Call the sync method if needs to be persisted to the database.

Signature

• collection(options: CollectionOptions): Collection

Parameter

All configuration parameters of options is consistent with the constructor of the Collection class, refer to Collection.

Event

• 'beforeDefineCollection': Trigger before defining the table.
• 'afterDefineCollection': Trigger after defining the table.

Example

db.collection({
  name: 'books',
  fields: [
    {
      type: 'string',
      name: 'title',
    },
    {
      type: 'float',
      name: 'price',
    },
  ],
});

// sync collection as table to db
await db.sync();

`getCollection()` Copy Section

Get a defined data table.

Signature

• getCollection(name: string): Collection

Parameter

Example

const collection = db.getCollection('books');

`hasCollection()` Copy Section

Check whether a specified data table is defined.

Signature

• hasCollection(name: string): boolean

Parameter

Example

db.collection({ name: 'books' });

db.hasCollection('books'); // true

db.hasCollection('authors'); // false

`removeCollection()` Copy Section

Remove a defined data table. It is to remove from memory only, call the sync method if needs to be persisted to the database.

Signature

• removeCollection(name: string): void

Parameter

Event

• 'beforeRemoveCollection': Trigger before removing the table.
• 'afterRemoveCollection': Trigger after removing the table

Example

db.collection({ name: 'books' });

db.removeCollection('books');

`import()` Copy Section

Load all files in the import file directory into memory as the configuration of collection.

Signature

• async import(options: { directory: string; extensions?: ImportFileExtension[] }): Promise<Map<string, Collection>>

Parameter

Example

The collection defined by file ./collections/books.ts is as below:

export default {
  name: 'books',
  fields: [
    {
      type: 'string',
      name: 'title',
    },
  ],
};

Import the relevant configurations when loading the plugin:

class Plugin {
  async load() {
    await this.app.db.import({
      directory: path.resolve(__dirname, './collections'),
    });
  }
}

Extension Registrations and Acquisitions Copy Chapter

`registerFieldTypes()` Copy Section

Register custom field type.

Signature

• registerFieldTypes(fieldTypes: MapOf<typeof Field>): void

Parameter

fieldTypes is a key-value pair, where key is the field type name, and value is the field type class.

Example

import { Field } from '@nocobase/database';

class MyField extends Field {
  // ...
}

db.registerFieldTypes({
  myField: MyField,
});

`registerModels()` Copy Section

Register custom data model class.

Signature

• registerModels(models: MapOf<ModelStatic<any>>): void

Parameter

models is a key-value pair, where key is the data model name, and value is the data model class.

Example

import { Model } from '@nocobase/database';

class MyModel extends Model {
  // ...
}

db.registerModels({
  myModel: MyModel,
});

db.collection({
  name: 'myCollection',
  model: 'myModel',
});

`registerRepositories()` Copy Section

Register custom data repository class.

Signature

• registerRepositories(repositories: MapOf<RepositoryType>): void

Parameter

repositories is a key-value pair, where key is the data repository name, and value is the data repository class.

Example

import { Repository } from '@nocobase/database';

class MyRepository extends Repository {
  // ...
}

db.registerRepositories({
  myRepository: MyRepository,
});

db.collection({
  name: 'myCollection',
  repository: 'myRepository',
});

`registerOperators()` Copy Section

Register custom data query operator.

Signature

• registerOperators(operators: MapOf<OperatorFunc>)

Parameter

operators is a key-value pair, where key is the operator name, and value is the generating function of the comparison operator statement.

Example

db.registerOperators({
  $dateOn(value) {
    return {
      [Op.and]: [
        { [Op.gte]: stringToDate(value) },
        { [Op.lt]: getNextDay(value) },
      ],
    };
  },
});

db.getRepository('books').count({
  filter: {
    createdAt: {
      // registered operator
      $dateOn: '2020-01-01',
    },
  },
});

`getModel()` Copy Section

Get the defined data model class. If no custom model class has been registered before, the default model class of Sequelize will be returned. The default name is the same as the name defined by collection.

Signature

• getModel(name: string): Model

Parameter

Example

db.registerModels({
  books: class MyModel extends Model {},
});

const ModelClass = db.getModel('books');

console.log(ModelClass.prototype instanceof MyModel); // true

Note: The model class retrieved from collection is not strictly equivalent to the model class at registration, but is inherited from the model class at registration. Since the properties of Sequelize's model class are modified during initialization, NocoBase automatically handles this inheritance relationship. All the definitions work fine except that the classes are not equal.

`getRepository()` Copy Section

Get the defined data repository class. If no custom data repository class has been registered before, the default data repository class of NocoBase will be returned. The default name is the same as the name defined by collection.

Data repository class is mainly used for the CRUD operations based on data model, refer to Repository.

Signature

• getRepository(name: string): Repository
• getRepository(name: string, relationId?: string | number): Repository

Parameter

When the name contains relationship in the form of 'tables.relactions', the related data repository class is returned. If the second parameter is provided, the data repository will be used (query, modify, etc.) based on the foreign key values of the relational data.

Example

Suppose there are two data tables posts and authors, and there is a foreign key in the posts table points to the authors table:

const AuthorsRepo = db.getRepository('authors');
const author1 = AuthorsRepo.create({ name: 'author1' });

const PostsRepo = db.getRepository('authors.posts', author1.id);
const post1 = AuthorsRepo.create({ title: 'post1' });
asset(post1.authorId === author1.id); // true

Database Events Copy Chapter

`on()` Copy Section

Listen for database events.

Signature

• on(event: string, listener: (...args: any[]) => void | Promise<void>): void

Parameter

Event name supports Model event of Sequelize by default. Global event is listened to by the name <sequelize_model_global_event>, single Model event is listened to by the name <model_name>. <sequelize_model_event>.

Refer to the Built-in Events section for parameter descriptions and detailed examples of all built-in event types.

`off()` Copy Section

Remove the event listener function.

Signature

• off(name: string, listener: Function)

Parameter

Example

const listener = async (model, options) => {
  console.log(model);
};

db.on('afterCreate', listener);

db.off('afterCreate', listener);

Database Operations Copy Chapter

`auth()` Copy Section

Database connection verification. It can be used to ensure that the application has established connection to the data.

Signature

• auth(options: QueryOptions & { retry?: number } = {}): Promise

Parameter

Example

await db.auth();

`reconnect()` Copy Section

Reconnect to the database.

Example

await db.reconnect();

`closed()` Copy Section

Check whether database has closed the connection.

Signature

• closed(): boolean

`close()` Copy Section

Closes database connection. Equivalent to sequelize.close().

`sync()` Copy Section

Synchronizes database table structure. Equivalent to sequelize.sync(), refer to Sequelize documentation for parameters.

`clean()` Copy Section

Empty the database, it will delete all data tables.

Signature

• clean(options: CleanOptions): Promise<void>

Parameter

Example

Remove all tables except for the users table.

await db.clean({
  drop: true,
  skip: ['users'],
});

Package-Level Export Copy Chapter

`defineCollection()` Copy Section

Create the configuration content of a data table.

Signature

• defineCollection(name: string, config: CollectionOptions): CollectionOptions

Parameter

Example

For the data table configuration file to be imported by db.import():

import { defineCollection } from '@nocobase/database';

export default defineCollection({
  name: 'users',
  fields: [
    {
      type: 'string',
      name: 'name',
    },
  ],
});

`extendCollection()` Copy Section

Extent the configuration content of a data table that is already in memory, mainly for the content of files imported by the import() method. This is the top-level package export method of @nocobase/database, and is not called through db instance. The extend alias can also be used.

Signature

• extendCollection(collectionOptions: CollectionOptions, mergeOptions?: MergeOptions): ExtendedCollectionOptions

Parameter

Example

Original definition of the table books (books.ts):

export default {
  name: 'books',
  fields: [{ name: 'title', type: 'string' }],
};

Extend the definition of the table books (books.extend.ts):

import { extend } from '@nocobase/database';

// Extend again
export default extend({
  name: 'books',
  fields: [{ name: 'price', type: 'number' }],
});

If the above two files are imported when calling import(), after being extended again by extend(), the table books will have title and price two fields.

This method is especially useful when extending the table structure that is already defined by existing plugin.

Built-in Events Copy Chapter

The following events will be triggered in the corresponding lifecycle of database, subscribe by the on() method and perform specific processing to meet some business needs.

`'beforeSync'` / `'afterSync'` Copy Section

Events triggered before or after a new table structure configuration (fields, indexes, etc.) is synchronized to the database. This is usually triggered when executing collection.sync() (internal call) for the logical processing of the extension of some special fields.

Signature

on(eventName: `${string}.beforeSync` | 'beforeSync' | `${string}.afterSync` | 'afterSync', listener: SyncListener): this

Type

import type { SyncOptions, HookReturn } from 'sequelize/types';

type SyncListener = (options?: SyncOptions) => HookReturn;

Example

const users = db.collection({
  name: 'users',
  fields: [{ type: 'string', name: 'username' }],
});

db.on('beforeSync', async (options) => {
  // do something
});

db.on('users.afterSync', async (options) => {
  // do something
});

await users.sync();

`'beforeValidate'` / `'afterValidate'` Copy Section

Before creating or updating data, there is a validation against the data based on the rules defined by the collection, and the corresponding events are triggered before and after the validation. This is triggered when repository.create() or repository.update() is called.

Signature

on(eventName: `${string}.beforeValidate` | 'beforeValidate' | `${string}.afterValidate` | 'afterValidate', listener: ValidateListener): this

Type

import type { ValidationOptions } from 'sequelize/types/lib/instance-validator';
import type { HookReturn } from 'sequelize/types';
import type { Model } from '@nocobase/database';

type ValidateListener = (
  model: Model,
  options?: ValidationOptions,
) => HookReturn;

Example

db.collection({
  name: 'tests',
  fields: [
    {
      type: 'string',
      name: 'email',
      validate: {
        isEmail: true,
      },
    },
  ],
});

// all models
db.on('beforeValidate', async (model, options) => {
  // do something
});
// tests model
db.on('tests.beforeValidate', async (model, options) => {
  // do something
});

// all models
db.on('afterValidate', async (model, options) => {
  // do something
});
// tests model
db.on('tests.afterValidate', async (model, options) => {
  // do something
});

const repository = db.getRepository('tests');
await repository.create({
  values: {
    email: 'abc', // checks for email format
  },
});
// or
await repository.update({
  filterByTk: 1,
  values: {
    email: 'abc', // checks for email format
  },
});

`'beforeCreate'` / `'afterCreate'` Copy Section

Events triggered before or after creating one piece of data. This is triggered when repository.create() is called.

Signature

on(eventName: `${string}.beforeCreate` | 'beforeCreate' | `${string}.afterCreate` | 'afterCreate', listener: CreateListener): this

Type

import type { CreateOptions, HookReturn } from 'sequelize/types';
import type { Model } from '@nocobase/database';

export type CreateListener = (
  model: Model,
  options?: CreateOptions,
) => HookReturn;

Example

db.on('beforeCreate', async (model, options) => {
  // do something
});

db.on('books.afterCreate', async (model, options) => {
  const { transaction } = options;
  const result = await model.constructor.findByPk(model.id, {
    transaction,
  });
  console.log(result);
});

`'beforeUpdate'` / `'afterUpdate'` Copy Section

Events triggered before or after updating one piece of data. This is triggered when repository.update() is called.

Signature

on(eventName: `${string}.beforeUpdate` | 'beforeUpdate' | `${string}.afterUpdate` | 'afterUpdate', listener: UpdateListener): this

Type

import type { UpdateOptions, HookReturn } from 'sequelize/types';
import type { Model } from '@nocobase/database';

export type UpdateListener = (
  model: Model,
  options?: UpdateOptions,
) => HookReturn;

Example

db.on('beforeUpdate', async (model, options) => {
  // do something
});

db.on('books.afterUpdate', async (model, options) => {
  // do something
});

`'beforeSave'` / `'afterSave'` Copy Section

Events triggered before or after creating or updating one piece of data. This is triggered when repository.create() or repository.update() is called.

Signature

on(eventName: `${string}.beforeSave` | 'beforeSave' | `${string}.afterSave` | 'afterSave', listener: SaveListener): this

Type

import type { SaveOptions, HookReturn } from 'sequelize/types';
import type { Model } from '@nocobase/database';

export type SaveListener = (model: Model, options?: SaveOptions) => HookReturn;

Example

db.on('beforeSave', async (model, options) => {
  // do something
});

db.on('books.afterSave', async (model, options) => {
  // do something
});

`'beforeDestroy'` / `'afterDestroy'` Copy Section

Events triggered before or after deleting one piece of data. This is triggered when repository.destroy() is called.

Signature

on(eventName: `${string}.beforeDestroy` | 'beforeDestroy' | `${string}.afterDestroy` | 'afterDestroy', listener: DestroyListener): this

Type

import type { DestroyOptions, HookReturn } from 'sequelize/types';
import type { Model } from '@nocobase/database';

export type DestroyListener = (
  model: Model,
  options?: DestroyOptions,
) => HookReturn;

Example

db.on('beforeDestroy', async (model, options) => {
  // do something
});

db.on('books.afterDestroy', async (model, options) => {
  // do something
});

`'afterCreateWithAssociations'` Copy Section

Events triggered after creating one piece of data that carries hierarchical data. This is triggered when repository.create() is called.

Signature

on(eventName: `${string}.afterCreateWithAssociations` | 'afterCreateWithAssociations', listener: CreateWithAssociationsListener): this

Type

import type { CreateOptions, HookReturn } from 'sequelize/types';
import type { Model } from '@nocobase/database';

export type CreateWithAssociationsListener = (
  model: Model,
  options?: CreateOptions,
) => HookReturn;

Example

db.on('afterCreateWithAssociations', async (model, options) => {
  // do something
});

db.on('books.afterCreateWithAssociations', async (model, options) => {
  // do something
});

`'afterUpdateWithAssociations'` Copy Section

Events triggered after updating one piece of data that carries hierarchical data. This is triggered when repository.update() is called.

Signature

on(eventName: `${string}.afterUpdateWithAssociations` | 'afterUpdateWithAssociations', listener: CreateWithAssociationsListener): this

Type

import type { UpdateOptions, HookReturn } from 'sequelize/types';
import type { Model } from '@nocobase/database';

export type UpdateWithAssociationsListener = (
  model: Model,
  options?: UpdateOptions,
) => HookReturn;

Example

db.on('afterUpdateWithAssociations', async (model, options) => {
  // do something
});

db.on('books.afterUpdateWithAssociations', async (model, options) => {
  // do something
});

`'afterSaveWithAssociations'` Copy Section

Events triggered after creating or updating one piece of data that carries hierarchical data. This is triggered when repository.create() or repository.update() is called.

Signature

on(eventName: `${string}.afterSaveWithAssociations` | 'afterSaveWithAssociations', listener: SaveWithAssociationsListener): this

Type

import type { SaveOptions, HookReturn } from 'sequelize/types';
import type { Model } from '@nocobase/database';

export type SaveWithAssociationsListener = (
  model: Model,
  options?: SaveOptions,
) => HookReturn;

Example

db.on('afterSaveWithAssociations', async (model, options) => {
  // do something
});

db.on('books.afterSaveWithAssociations', async (model, options) => {
  // do something
});

`'beforeDefineCollection'` Copy Section

Events triggered before defining a data table, such as when db.collection() is called.

Note: This is a synchronous event.

Signature

on(eventName: 'beforeDefineCollection', listener: BeforeDefineCollectionListener): this

Type

import type { CollectionOptions } from '@nocobase/database';

export type BeforeDefineCollectionListener = (
  options: CollectionOptions,
) => void;

Example

db.on('beforeDefineCollection', (options) => {
  // do something
});

`'afterDefineCollection'` Copy Section

Events triggered after defining a data table, such as when db.collection() is called.

Note: This is a synchronous event.

Signature

on(eventName: 'afterDefineCollection', listener: AfterDefineCollectionListener): this

Type

import type { Collection } from '@nocobase/database';

export type AfterDefineCollectionListener = (options: Collection) => void;

Example

db.on('afterDefineCollection', (collection) => {
  // do something
});

`'beforeRemoveCollection'` / `'afterRemoveCollection'` Copy Section

Events triggered before or after removing a data table from memory, such as when db.removeCollection() is called.

Note: This is a synchronous event.

Signature

on(eventName: 'beforeRemoveCollection' | 'afterRemoveCollection', listener: RemoveCollectionListener): this

Type

import type { Collection } from '@nocobase/database';

export type RemoveCollectionListener = (options: Collection) => void;

Example

db.on('beforeRemoveCollection', (collection) => {
  // do something
});

db.on('afterRemoveCollection', (collection) => {
  // do something
});

File: docs/en-US/api/database/operators.md Copy Chapter

Filter Operators

Used in the filter parameters of the find, findOne, findAndCount, count, etc. APIs of repository:

const repository = db.getRepository('books');

repository.find({
  filter: {
    title: {
      $eq: 'Spring and Autumn',
    },
  },
});

To support JSON, NocoBase identifies query operators as a string prefixed with $.

Moreover, NocoBase provides API to extend operators. Refer to db.registerOperators().

General Operators Copy Chapter

`$eq` Copy Section

Check if the field value is equal to the specified value. Equivalent to = in SQL.

Example

repository.find({
  filter: {
    title: {
      $eq: 'Spring and Autumn',
    },
  },
});

Equal to title: 'Spring and Autumn'

`$ne` Copy Section

Check if the field value is not equal to the specified value. Equivalent to != in SQL.

Example

repository.find({
  filter: {
    title: {
      $ne: 'Spring and Autumn',
    },
  },
});

`$is` Copy Section

Check if the field value is the specified value. Equivalent to IS in SQL.

Example

repository.find({
  filter: {
    title: {
      $is: null,
    },
  },
});

`$not` Copy Section

Check if the field value is not the specified value. Equivalent to IS NOT in SQL.

Example

repository.find({
  filter: {
    title: {
      $not: null,
    },
  },
});

`$col` Copy Section

Check if the field value is equal to the value of another field. Equivalent to = in SQL.

Example

repository.find({
  filter: {
    title: {
      $col: 'name',
    },
  },
});

`$in` Copy Section

Check if the field value is in the specified array. Equivalent to IN in SQL.

Example

repository.find({
  filter: {
    title: {
      $in: ['Spring and Autumn', 'Warring States'],
    },
  },
});

`$notIn` Copy Section

Check if the field value is not in the specified array. Equivalent to NOT IN in SQL.

Example

repository.find({
  filter: {
    title: {
      $notIn: ['Spring and Autumn', 'Warring States'],
    },
  },
});

`$empty` Copy Section

Check if the general field is empty. For string field, check if it is an empty string; for array field, check if it is an empty array.

Example

repository.find({
  filter: {
    title: {
      $empty: true,
    },
  },
});

`$notEmpty` Copy Section

Check if the general field is not empty. For string field, check if it is not an empty string; for array field, check if it is not an empty array.

Example

repository.find({
  filter: {
    title: {
      $notEmpty: true,
    },
  },
});

Logical Operators Copy Chapter

`$and` Copy Section

Logical AND. Equivalent to AND in SQL.

Example

repository.find({
  filter: {
    $and: [{ title: 'Book of Songs' }, { isbn: '1234567890' }],
  },
});

`$or` Copy Section

Logical OR. Equivalent to OR in SQL.

Example

repository.find({
  filter: {
    $or: [
      { title: 'Book of Songs' },
      { publishedAt: { $lt: '0000-00-00T00:00:00Z' } },
    ],
  },
});

Boolean Field Operators Copy Chapter

For boolean fields: type: 'boolean'

`$isFalsy` Copy Section

Check if a Boolean field value is false. Boolean field values of false, 0 and NULL are all judged to be $isFalsy: true.

Example

repository.find({
  filter: {
    isPublished: {
      $isFalsy: true,
    },
  },
});

`$isTruly` Copy Section

Check if a Boolean field value is true. Boolean field values of true and 1 are all judged to be $isTruly: true.

Example

repository.find({
  filter: {
    isPublished: {
      $isTruly: true,
    },
  },
});

Numeric Type Field Operators Copy Chapter

For numeric type fields, including:

• type: 'integer'
• type: 'float'
• type: 'double'
• type: 'real'
• type: 'decimal'

`$gt` Copy Section

Check if the field value is greater than the specified value. Equivalent to > in SQL.

Example

repository.find({
  filter: {
    price: {
      $gt: 100,
    },
  },
});

`$gte` Copy Section

Check if the field value is equal to or greater than the specified value. Equivalent to >= in SQL.

Example

repository.find({
  filter: {
    price: {
      $gte: 100,
    },
  },
});

`$lt` Copy Section

Check if the field value is less than the specified value. Equivalent to < in SQL.

Example

repository.find({
  filter: {
    price: {
      $lt: 100,
    },
  },
});

`$lte` Copy Section

Check if the field value is equal to or less than the specified value. Equivalent to <= in SQL.

Example

repository.find({
  filter: {
    price: {
      $lte: 100,
    },
  },
});

`$between` Copy Section

Check if the field value is between the specified two values. Equivalent to BETWEEN in SQL.

Example

repository.find({
  filter: {
    price: {
      $between: [100, 200],
    },
  },
});

`$notBetween` Copy Section

Check if the field value is not between the specified two values. Equivalent to NOT BETWEEN in SQL.

Example

repository.find({
  filter: {
    price: {
      $notBetween: [100, 200],
    },
  },
});

String Type Field Operators Copy Chapter

For string type fields, including string.

`$includes` Copy Section

Check if the string field contains the specified substring.

Example

repository.find({
  filter: {
    title: {
      $includes: 'Three Character Classic',
    },
  },
});

`$notIncludes` Copy Section

Check if the string field does not contain the specified substring.

Example

repository.find({
  filter: {
    title: {
      $notIncludes: 'Three Character Classic',
    },
  },
});

`$startsWith` Copy Section

Check if the string field starts with the specified substring.

Example

repository.find({
  filter: {
    title: {
      $startsWith: 'Three Character Classic',
    },
  },
});

`$notStatsWith` Copy Section

Check if the string field does not start with the specified substring.

Example

repository.find({
  filter: {
    title: {
      $notStatsWith: 'Three Character Classic',
    },
  },
});

`$endsWith` Copy Section

Check if the string field ends with the specified substring.

Example

repository.find({
  filter: {
    title: {
      $endsWith: 'Three Character Classic',
    },
  },
});

`$notEndsWith` Copy Section

Check if the string field does not end with the specified substring.

Example

repository.find({
  filter: {
    title: {
      $notEndsWith: 'Three Character Classic',
    },
  },
});

`$like` Copy Section

Check if the field value contains the specified string. Equivalent to LIKE in SQL.

Example

repository.find({
  filter: {
    title: {
      $like: 'Computer',
    },
  },
});

`$notLike` Copy Section

Check if the field value does not contain the specified string. Equivalent to NOT LIKE in SQL.

Example

repository.find({
  filter: {
    title: {
      $notLike: 'Computer',
    },
  },
});

`$iLike` Copy Section

Check if a field value contains the specified string, case ignored. Equivalent to ILIKE in SQL (PG only).

Example

repository.find({
  filter: {
    title: {
      $iLike: 'Computer',
    },
  },
});

`$notILike` Copy Section

Check if a field value does not contain the specified string, case ignored. Equivalent to NOT ILIKE in SQL (PG only).

Example

repository.find({
  filter: {
    title: {
      $notILike: 'Computer',
    },
  },
});

`$regexp` Copy Section

Check if the field value matches the specified regular expression. Equivalent to REGEXP in SQL (PG only).

Example

repository.find({
  filter: {
    title: {
      $regexp: '^Computer',
    },
  },
});

`$notRegexp` Copy Section

Check if the field value does not match the specified regular expression. Equivalent to NOT REGEXP in SQL (PG only).

Example

repository.find({
  filter: {
    title: {
      $notRegexp: '^Computer',
    },
  },
});

`$iRegexp` Copy Section

Check if the field value matches the specified regular expression, case ignored. Equivalent to ~* in SQL (PG only).

Example

repository.find({
  filter: {
    title: {
      $iRegexp: '^COMPUTER',
    },
  },
});

`$notIRegexp` Copy Section

Check if the field value does not match the specified regular expression, case ignored. Equivalent to !~* in SQL (PG only).

Example

repository.find({
  filter: {
    title: {
      $notIRegexp: '^COMPUTER',
    },
  },
});

Date Type Field Operators Copy Chapter

For date type fields: type: 'date'

`$dateOn` Copy Section

Check if the date field value is within a certain day.

Example

repository.find({
  filter: {
    createdAt: {
      $dateOn: '2021-01-01',
    },
  },
});

`$dateNotOn` Copy Section

Check if the date field value is not within a certain day.

Example

repository.find({
  filter: {
    createdAt: {
      $dateNotOn: '2021-01-01',
    },
  },
});

`$dateBefore` Copy Section

Check if the date field value is before a certain value, i.e., less than the one passed in.

Example

repository.find({
  filter: {
    createdAt: {
      $dateBefore: '2021-01-01T00:00:00.000Z',
    },
  },
});

`$dateNotBefore` Copy Section

Check if the date field value is not before a certain value, i.e., equal to or greater than the one passed in.

Example

repository.find({
  filter: {
    createdAt: {
      $dateNotBefore: '2021-01-01T00:00:00.000Z',
    },
  },
});

`$dateAfter` Copy Section

Check if the date field value is after a certain value, i.e., greater than the one passed in.

Example

repository.find({
  filter: {
    createdAt: {
      $dateAfter: '2021-01-01T00:00:00.000Z',
    },
  },
});

`$dateNotAfter` Copy Section

Check if the date field value is not after a certain value, i.e., equal to or greater than the one passed in.

Example

repository.find({
  filter: {
    createdAt: {
      $dateNotAfter: '2021-01-01T00:00:00.000Z',
    },
  },
});

Array Type Field Operators Copy Chapter

For array type fields: type: 'array'

`$match` Copy Section

Check if the array field values match values of the specified array.

Example

repository.find({
  filter: {
    tags: {
      $match: ['literature', 'history'],
    },
  },
});

`$notMatch` Copy Section

Check if the array field values do not match values of the specified array.

Example

repository.find({
  filter: {
    tags: {
      $notMatch: ['literature', 'history'],
    },
  },
});

`$anyOf` Copy Section

Check if the array field values contain any of the values of the specified array.

Example

repository.find({
  filter: {
    tags: {
      $anyOf: ['literature', 'history'],
    },
  },
});

`$noneOf` Copy Section

Check if the array field values contain none of the values of the specified array.

Example

repository.find({
  filter: {
    tags: {
      $noneOf: ['literature', 'history'],
    },
  },
});

`$arrayEmpty` Copy Section

Check if the array field is empty.

Example

repository.find({
  filter: {
    tags: {
      $arrayEmpty: true,
    },
  },
});

`$arrayNotEmpty` Copy Section

Check if the array field is not empty.

Example

repository.find({
  filter: {
    tags: {
      $arrayNotEmpty: true,
    },
  },
});

Relational Field Type Operators Copy Chapter

For checking if a relationship exists, field types include:

• type: 'hasOne'
• type: 'hasMany'
• type: 'belongsTo'
• type: 'belongsToMany'

`$exists` Copy Section

There is relational data existing.

Example

repository.find({
  filter: {
    author: {
      $exists: true,
    },
  },
});

`$notExists` Copy Section

There is no relational data existing.

Example

repository.find({
  filter: {
    author: {
      $notExists: true,
    },
  },
});

File: docs/en-US/api/database/repository.md Copy Chapter

Repository

Overview Copy Chapter

On a given Collection object, you can get its Repository object to perform read and write operations on the data table.

const { UserCollection } = require('./collections');

const UserRepository = UserCollection.repository;

const user = await UserRepository.findOne({
  filter: {
    id: 1,
  },
});

user.name = 'new name';
await user.save();

Query Copy Section

Basic Query

On the Repository object, call the find* methods to perform query. The filter parameter is supported by all query methods to filter the data.

// SELECT * FROM users WHERE id = 1
userRepository.find({
  filter: {
    id: 1,
  },
});

Operator

The filter parameter in the Repository also provides a variety of operators to perform more diverse queries.

// SELECT * FROM users WHERE age > 18
userRepository.find({
  filter: {
    age: {
      $gt: 18,
    },
  },
});

// SELECT * FROM users WHERE age > 18 OR name LIKE '%张%'
userRepository.find({
  filter: {
    $or: [{ age: { $gt: 18 } }, { name: { $like: '%张%' } }],
  },
});

Refer to Filter Operators for more details on operators.

Field Control

Control the output fields by the fields, except, and appends parameters when performing query.

• fields: Specify output fields
• except: Exclude output fields
• appends: Append output associated fields

// The result contains only the id and name fields
userRepository.find({
  fields: ['id', 'name'],
});

// The result does not contain only the password field
userRepository.find({
  except: ['password'],
});

// The result contains data associated with the posts object
userRepository.find({
  appends: ['posts'],
});

Associated Field Query

The filter parameter supports filtering by associated fields, for example:

// Find the user objects whose associated posts have title of "post title"
userRepository.find({
  filter: {
    'posts.title': 'post title',
  },
});

Associated fields can also be nested:

// Find the user objects whose associated posts have comments containing "keywords"
await userRepository.find({
  filter: {
    'posts.comments.content': {
      $like: '%keywords%',
    },
  },
});

Sort

Sort query results by the sort parameter.

// SELECT * FROM users ORDER BY age
await userRepository.find({
  sort: 'age',
});

// SELECT * FROM users ORDER BY age DESC
await userRepository.find({
  sort: '-age',
});

// SELECT * FROM users ORDER BY age DESC, name ASC
await userRepository.find({
  sort: ['-age', 'name'],
});

Sort by the field of the associated object is also supported:

await userRepository.find({
  sort: 'profile.createdAt',
});

Create Copy Section

Basic Create

Create new data objects via Repository.

await userRepository.create({
  name: 'Mark',
  age: 18,
});
// INSERT INTO users (name, age) VALUES ('Mark', 18)

// Bulk creation
await userRepository.create([
  {
    name: 'Mark',
    age: 18,
  },
  {
    name: 'Alex',
    age: 20,
  },
]);

Create Association

Create associated objects at the same time of creating data. Like query, nested use of associated objects is also supported. For example:

await userRepository.create({
  name: 'Mark',
  age: 18,
  posts: [
    {
      title: 'post title',
      content: 'post content',
      tags: [
        {
          name: 'tag1',
        },
        {
          name: 'tag2',
        },
      ],
    },
  ],
});
// When creating a user, create a post to associate with the user, and create tags to associate with the post

If the associated object is already in the database, you can pass its ID to create an association with it.

const tag1 = await tagRepository.findOne({
  filter: {
    name: 'tag1',
  },
});

await userRepository.create({
  name: 'Mark',
  age: 18,
  posts: [
    {
      title: 'post title',
      content: 'post content',
      tags: [
        {
          id: tag1.id, // Create an association with an existing associated object
        },
        {
          name: 'tag2',
        },
      ],
    },
  ],
});

Update Copy Section

Basic Update

After getting the data object, you can modify the properties directly on the data object (Model), and then call the save method to save the changes.

const user = await userRepository.findOne({
  filter: {
    name: 'Mark',
  },
});

user.age = 20;
await user.save();

The data object Model is inherited from Sequelize Model, refer to Sequelize Model for the operations on Model.

Or update data via Repository:

// Update the records that meet the filtering condition
await userRepository.update({
  filter: {
    name: 'Mark',
  },
  values: {
    age: 20,
  },
});

Control which fields to update by the whitelist and blacklist parameters, for example:

await userRepository.update({
  filter: {
    name: 'Mark',
  },
  values: {
    age: 20,
    name: 'Alex',
  },
  whitelist: ['age'], // Only update the age field
});

Update Associated Field

Associated objects can be set while updating, for example:

const tag1 = tagRepository.findOne({
  filter: {
    id: 1,
  },
});

await postRepository.update({
  filter: {
    id: 1,
  },
  values: {
    title: 'new post title',
    tags: [
      {
        id: tag1.id, // Associate with tag1
      },
      {
        name: 'tag2', // Create new tag and associate with it
      },
    ],
  },
});

await postRepository.update({
  filter: {
    id: 1,
  },
  values: {
    tags: null, // Disassociate post from tags
  },
});

Delete Copy Section

Call the destroy() method in Repository to perform the deletion operation. Filtering condition has to be specified to delete.

await userRepository.destroy({
  filter: {
    status: 'blocked',
  },
});

Constructor Copy Chapter

It is usually not called directly by the developer, the instantiation is done mainly by specifying a corresponding repository type that is already registered in the parameter of db.colletion(). Repository type is registered through db.registerRepositories().

Signature

• constructor(collection: Collection)

Example

import { Repository } from '@nocobase/database';

class MyRepository extends Repository {
  async myQuery(sql) {
    return this.database.sequelize.query(sql);
  }
}

db.registerRepositories({
  books: MyRepository,
});

db.collection({
  name: 'books',
  // here link to the registered repository
  repository: 'books',
});

await db.sync();

const books = db.getRepository('books') as MyRepository;
await books.myQuery('SELECT * FROM books;');

Instance Members Copy Chapter

`database` Copy Section

The database management instance where the context is located.

`collection` Copy Section

The corresponding data table management instance.

`model` Copy Section

The corresponding data model class.

Instance Methods Copy Chapter

`find()` Copy Section

Find datasets from the database with the specified filtering conditions and sorting, etc.

Signature

• async find(options?: FindOptions): Promise<Model[]>

Type

type Filter = FilterWithOperator | FilterWithValue | FilterAnd | FilterOr;
type Appends = string[];
type Except = string[];
type Fields = string[];
type Sort = string[] | string;

interface SequelizeFindOptions {
  limit?: number;
  offset?: number;
}

interface FilterByTk {
  filterByTk?: TargetKey;
}

interface CommonFindOptions extends Transactionable {
  filter?: Filter;
  fields?: Fields;
  appends?: Appends;
  except?: Except;
  sort?: Sort;
}

type FindOptions = SequelizeFindOptions & CommonFindOptions & FilterByTk;

Detailed Information

`filter: Filter`

Query conditions for filtering data results. In the query parameters that passed in, key is the name of the field, value is the corresponding value. Operators can be used in conjunction with other filtering conditions.

// Find records with name "foo" and age above 18
repository.find({
  filter: {
    name: 'foo',
    age: {
      $gt: 18,
    },
  },
});

Refer to Operators for more information.

`filterByTk: TargetKey`

Query data by TargetKey, this is shortcut for the filter parameter. The field of TargetKey can be configured in Collection, the default is primaryKey.

// By default, find records with id 1
repository.find({
  filterByTk: 1,
});

`fields: string[]`

Query columns. It is used to control which data fields to output. With this parameter, only the specified fields will be returned.

`except: string[]`

Exclude columns. It is used to control which data fields to output. With this parameter, the specified fields will not be returned.

`appends: string[]`

Append columns. It is used to load associated data. With this parameter, the specified associated fields will be returned together.

`sort: string[] | string`

Specify the sorting method of the query results. The input parameter is the name of the field, by default is to sort in the ascending order (asc); a - symbol needs to be added before the field name to sort in the descending order (desc). For example, ['-id', 'name'] means to sort by id desc, name asc.

`limit: number`

Limit the number of results, same as limit in SQL.

`offset: number`

The offset of the query, same as offset in SQL.

Example

const posts = db.getRepository('posts');

const results = await posts.find({
  filter: {
    createdAt: {
      $gt: '2022-01-01T00:00:00.000Z',
    },
  },
  fields: ['title'],
  appends: ['user'],
});

`findOne()` Copy Section

Find a single piece of data from the database for specific conditions. Equivalent to Model.findOne() in Sequelize.

Signature

• async findOne(options?: FindOneOptions): Promise<Model | null>

Example

const posts = db.getRepository('posts');

const result = await posts.findOne({
  filterByTk: 1,
});

`count()` Copy Section

Query a certain amount of data from the database for specific conditions. Equivalent to Model.count() in Sequelize.

Signature

• count(options?: CountOptions): Promise<number>

Type

interface CountOptions
  extends Omit<SequelizeCountOptions, 'distinct' | 'where' | 'include'>,
    Transactionable {
  filter?: Filter;
}

Example

const books = db.getRepository('books');

const count = await books.count({
  filter: {
    title: 'Three character classic',
  },
});

`findAndCount()` Copy Section

Find datasets from the database with the specified filtering conditions and return the number of results. Equivalent to Model.findAndCountAll() in Sequelize.

Signature

• async findAndCount(options?: FindAndCountOptions): Promise<[Model[], number]>

Type

type FindAndCountOptions = Omit<
  SequelizeAndCountOptions,
  'where' | 'include' | 'order'
> &
  CommonFindOptions;

Detailed Information

The query parameters are the same as find(). An array is returned with the first element of the query results, and the second element of the total number of results.

`create()` Copy Section

Inserts a newly created data into the data table. Equivalent to Model.create() in Sequelize. When the data object to be created carries any associated field, the corresponding associated data record is created or updated along with it.

Signature

• async create<M extends Model>(options: CreateOptions): Promise<M>

Example

const posts = db.getRepository('posts');

const result = await posts.create({
  values: {
    title: 'NocoBase 1.0 Release Notes',
    tags: [
      // Update data when there is a primary key and value of the associated table
      { id: 1 },
      // Create data when there is no primary key and value
      { name: 'NocoBase' },
    ],
  },
});

`createMany()` Copy Section

Inserts multiple newly created data into the data table. This is equivalent to calling the create() method multiple times.

Signature

• createMany(options: CreateManyOptions): Promise<Model[]>

Type

interface CreateManyOptions extends BulkCreateOptions {
  records: Values[];
}

Detailed Information

• records: An array of data objects to be created.
• transaction: Transaction object. If no transaction parameter is passed, the method will automatically create an internal transaction.

Example

const posts = db.getRepository('posts');

const results = await posts.createMany({
  records: [
    {
      title: 'NocoBase 1.0 Release Notes',
      tags: [
        // Update data when there is a primary key and value of the associated table
        { id: 1 },
        // Create data when there is no primary key and value
        { name: 'NocoBase' },
      ],
    },
    {
      title: 'NocoBase 1.1 Release Notes',
      tags: [{ id: 1 }],
    },
  ],
});

`update()` Copy Section

Update data in the data table. Equivalent to Model.update() in Sequelize. When the data object to be updated carries any associated field, the corresponding associated data record is created or updated along with it.

Signature

• async update<M extends Model>(options: UpdateOptions): Promise<M>

Example

const posts = db.getRepository('posts');

const result = await posts.update({
  filterByTk: 1,
  values: {
    title: 'NocoBase 1.0 Release Notes',
    tags: [
      // Update data when there is a primary key and value of the associated table
      { id: 1 },
      // Create data when there is no primary key and value
      { name: 'NocoBase' },
    ],
  },
});

`destroy()` Copy Section

Delete data from the data table. Equivalent to Model.destroy() in Sequelize.

Signature

• async destroy(options?: TargetKey | TargetKey[] | DestoryOptions): Promise<number>

Type

interface DestroyOptions extends SequelizeDestroyOptions {
  filter?: Filter;
  filterByTk?: TargetKey | TargetKey[];
  truncate?: boolean;
  context?: any;
}

Detailed Information

• filter：Specify the filtering conditions of the records to be deleted. Refer to the find() method for the detailed usage of the filter.
• filterByTk：Specify the filtering conditions by TargetKey.
• truncate: Whether to empty the table data, this parameter is valid if no filter or filterByTk parameter is passed.
• transaction: Transaction object. If no transaction parameter is passed, the method will automatically create an internal transaction.

File: docs/en-US/api/database/shared.md Copy Chapter

Parameters

File: docs/en-US/api/database/interfaces/base-interface.md Copy Chapter

BaseInterface

Overview Copy Chapter

BaseInterface is the foundational class for all Interface types. Users can extend this class to implement custom Interface logic.

class CustomInterface extends BaseInterface {
  async toValue(value: string, ctx?: any): Promise<any> {
    // Custom toValue logic
  }

  toString(value: any, ctx?: any) {
    // Custom toString logic
  }
}
// Register Interface
db.interfaceManager.registerInterfaceType('customInterface', CustomInterface)

Interfaces Copy Chapter

toValue(value: string, ctx?: any): Promise Copy Section

Converts an external string to the actual value of the interface, which can be directly passed to the Repository for write operations.

toString(value: any, ctx?: any) Copy Section

Converts the actual value of the interface to a string type, which can be used for exporting or displaying purposes.

File: docs/en-US/api/database/relation-repository/belongs-to-many-repository.md Copy Chapter

BelongsToManyRepository

BelongsToManyRepository is the Relation Repository for handling BelongsToMany relationships.

Unlike other relationship types, the BelongsToMany type of relationship needs to be recorded through an intermediate table. The intermediate table can be created automatically or explicitly specified when defining association relationships in NocoBase.

Class Methods Copy Chapter

`find()` Copy Section

Find associated objects.

Signature

• async find(options?: FindOptions): Promise<M[]>

Detailed Information

Query parameters are the same as Repository.find().

`findOne()` Copy Section

Find associated objects, only to return one record.

Signature

• async findOne(options?: FindOneOptions): Promise<M>

`count()` Copy Section

Return the number of records matching the query criteria.

Signature

• async count(options?: CountOptions)

Type

interface CountOptions
  extends Omit<SequelizeCountOptions, 'distinct' | 'where' | 'include'>,
    Transactionable {
  filter?: Filter;
}

`findAndCount()` Copy Section

Find datasets from the database with the specified filtering conditions and return the number of results.

Signature

• async findAndCount(options?: FindAndCountOptions): Promise<[any[], number]>

Type

type FindAndCountOptions = CommonFindOptions;

`create()` Copy Section

Create associated objects.

Signature

• async create(options?: CreateOptions): Promise<M>

`update()` Copy Section

Update associated objects that match the conditions.

Signature

• async update(options?: UpdateOptions): Promise<M>

`destroy()` Copy Section

Delete associated objects.

Signature

• async destroy(options?: TargetKey | TargetKey[] | DestroyOptions): Promise

`add()` Copy Section

Add new associated objects.

Signature

• async add( options: TargetKey | TargetKey[] | PrimaryKeyWithThroughValues | PrimaryKeyWithThroughValues[] | AssociatedOptions ): Promise<void>

Type

type PrimaryKeyWithThroughValues = [TargetKey, Values];

interface AssociatedOptions extends Transactionable {
  tk?:
    | TargetKey
    | TargetKey[]
    | PrimaryKeyWithThroughValues
    | PrimaryKeyWithThroughValues[];
}

Detailed Information

Pass the targetKey of the associated object directly, or pass the targetKey along with the field values of the intermediate table.

Example

const t1 = await Tag.repository.create({
  values: { name: 't1' },
});

const t2 = await Tag.repository.create({
  values: { name: 't2' },
});

const p1 = await Post.repository.create({
  values: { title: 'p1' },
});

const PostTagRepository = new BelongsToManyRepository(Post, 'tags', p1.id);

// Pass in the targetKey
PostTagRepository.add([t1.id, t2.id]);

// Pass in intermediate table fields
PostTagRepository.add([
  [t1.id, { tagged_at: '123' }],
  [t2.id, { tagged_at: '456' }],
]);

`set()` Copy Section