---

Model Alias Configuration

This guide explains how to use human-friendly model aliases to access datasets, and how to generate the configuration automatically with the CLI.

Why Model Aliases?

On the Lovrabet platform, every dataset has a unique datasetCode (for example, 8d2dcbae08b54bdd84c00be558ed48df) — a system-generated hash ID.

Without aliases:

// 使用 datasetCode 访问（不易读）
const orders = await client.models.dataset_8d2dcbae08b54bdd84c00be558ed48df.filter();
const customers = await client.models.dataset_a1b2c3d4e5f6789012345678abcdef12.filter();
const products = await client.models.dataset_f9e8d7c6b5a4321098765432fedcba98.filter();

With aliases:

// 使用别名访问（清晰易读）
const orders = await client.models.orders.filter();
const customers = await client.models.customers.filter();
const products = await client.models.products.filter();

Model aliases make your code:

• ✅ More readable - You can tell at a glance which table you're working with
• ✅ Easier to maintain - No need to memorize hash IDs
• ✅ Team friendly - Easier code reviews and handoffs

Two Ways to Configure

Option 1: Generate with the CLI (recommended)

Run lovrabet api pull to generate the configuration files automatically — no manual writing required.

lovrabet api pull

💡 Prerequisite Make sure the CLI is installed and you are logged in before running it.

This generates two files in your project:

src/api/api.ts - Model configuration:

import { registerModels, type ModelsConfig } from "@lovrabet/sdk";

export const LOVRABET_MODELS_CONFIG: ModelsConfig = {
  appCode: "your-app-code",
  models: [
    {
      datasetCode: "8d2dcbae08b54bdd84c00be558ed48df",
      tableName: "orders",
      alias: "orders"
    },
    {
      datasetCode: "a1b2c3d4e5f6789012345678abcdef12",
      tableName: "customers",
      alias: "customers"
    },
    {
      datasetCode: "f9e8d7c6b5a4321098765432fedcba98",
      tableName: "products",
      alias: "products"
    },
    // ... 自动生成所有数据集
  ],
};

registerModels(LOVRABET_MODELS_CONFIG);

src/api/client.ts - A ready-made client:

import { createClient } from "@lovrabet/sdk";
import "./api"; // 自动注册配置

export const lovrabetClient = createClient();

Use in Your Project

import { lovrabetClient } from "@/api/client";

// 直接使用别名访问
const orders = await lovrabetClient.models.orders.filter();
const customers = await lovrabetClient.models.customers.filter();
const products = await lovrabetClient.models.products.filter();

💡 Full CLI guide For more ways to use the CLI, see Auto-generate SDK configuration.

Option 2: Manual Configuration

If you don't use the CLI, you can configure model aliases by hand.

import { createClient } from "@lovrabet/sdk";

const client = createClient({
  appCode: "your-app-code",
  models: [
    {
      datasetCode: "8d2dcbae08b54bdd84c00be558ed48df",
      tableName: "orders",
      alias: "orders"
    },
    {
      datasetCode: "a1b2c3d4e5f6789012345678abcdef12",
      tableName: "customers",
      alias: "customers"
    },
  ],
});

// 使用别名访问
const orders = await client.models.orders.filter();

Alias Naming Rules

CLI Naming Rules

The CLI converts table names to camelCase aliases automatically:

Table name	Generated alias
orders	orders
order_items	orderItems
user_profile	userProfile
sales_records	salesRecords
product_categories	productCategories

Naming Guidelines for Manual Configuration

If you configure aliases manually, follow these rules:

1. Use camelCase - Consistent with JavaScript naming conventions
2. Be descriptive - The alias should clearly convey what the table is for
3. Avoid conflicts - Keep every alias unique within your project
4. Keep it short - Avoid overly long aliases

// ✅ 好的别名
{ alias: "orders" }
{ alias: "orderItems" }
{ alias: "userProfile" }

// ❌ 不推荐的别名
{ alias: "o" }  // 太简短，不清晰
{ alias: "order_items" }  // 使用了下划线
{ alias: "theOrderItemsTable" }  // 太冗长

Access Style Comparison

Once aliases are configured, the SDK supports three access styles:

// 方式 1：使用别名（推荐）
client.models.orders.filter()

// 方式 2：使用 dataset_ 前缀 + datasetCode
client.models.dataset_8d2dcbae08b54bdd84c00be558ed48df.filter()

// 方式 3：使用数组索引访问（不推荐）
client.models["dataset_8d2dcbae08b54bdd84c00be558ed48df"].filter()

All three are functionally identical, but the alias style is strongly recommended — it produces the clearest, most readable code.

TypeScript Support

With aliases, TypeScript provides full type hints and autocomplete.

import { lovrabetClient } from "@/api/client";

// TypeScript 会自动提示所有可用的模型别名
lovrabetClient.models.  // 输入 . 后会显示：orders, customers, products...

// 类型安全的方法调用
const orders = await lovrabetClient.models.orders.filter({
  where: { status: { $eq: 'pending' } },  // 完整的类型提示
  pageSize: 20,
});

Updating the Configuration

When your Lovrabet workspace changes (tables added or removed), regenerate the configuration.

Update with the CLI

lovrabet api pull

The CLI automatically:

• Adds configuration for new datasets
• Removes deleted datasets
• Updates changed dataset information

Update Manually

If you configured manually:

1. Open the dataset list in the Lovrabet workspace
2. Copy the new dataset's datasetCode
3. Add the new model entry to your configuration file

FAQ

Q: Can I use both aliases and datasetCodes?

Yes. Once aliases are configured, both styles work:

// 使用别名
await client.models.orders.filter();

// 使用 datasetCode（仍然有效）
await client.models.dataset_8d2dcbae08b54bdd84c00be558ed48df.filter();

Q: What if two aliases collide?

If two tables would generate the same alias (for example, both user and users could yield user), the CLI resolves the conflict automatically.

For manual configuration, make sure every alias is unique:

models: [
  { datasetCode: "xxx", tableName: "user", alias: "user" },
  { datasetCode: "yyy", tableName: "users", alias: "users" },  // 不同的别名
]

Q: Can I skip aliases entirely?

Yes. Without an alias, you can still access models with the dataset_ prefix:

const client = createClient({
  appCode: "your-app-code",
  accessKey: process.env.LOVRABET_ACCESS_KEY,
  models: [
    { datasetCode: "8d2dcbae08b54bdd84c00be558ed48df", tableName: "orders" },
    // 没有配置 alias
  ],
});

// 使用 datasetCode 访问
await client.models.dataset_8d2dcbae08b54bdd84c00be558ed48df.filter();

That said, configuring aliases is strongly recommended for readability.

Q: Can the alias differ from the table name?

Yes. Aliases are fully customizable:

models: [
  {
    datasetCode: "8d2dcbae08b54bdd84c00be558ed48df",
    tableName: "t_order",  // 数据库表名
    alias: "orders"        // 自定义别名（更友好）
  },
]

Q: When do I need to re-pull the configuration?

Re-run lovrabet api pull when:

• ✅ A table is added
• ✅ A table is deleted
• ✅ A table is renamed
• ❌ Table fields change (no re-pull needed)
• ❌ Table data changes (no re-pull needed)

Related Documentation

• Auto-generate SDK configuration - Full CLI guide
• SDK configuration guide - Complete configuration reference
• Quick start - SDK basics
• TypeScript support - Type-safe development