# Set up with an AI agent > A ready-to-copy prompt so Claude Code, Cursor or Codex can read the DataxLand docs and connect MCP for you. The DataxLand docs have a Markdown version for AI agents. Paste the prompt below into the coding agent on your machine: ```text Read https://dataxland.com/en/docs/mcp.md and https://dataxland.com/llms.txt. Help me add an MCP server named "dataxland" to your MCP configuration with the token I will paste, then call the tool that lists metrics to check the connection. Do not save the token to any file in the repo. ``` ## Resources for agents | Path | Contents | | --- | --- | | [/llms.txt](/llms.txt) | Index of the docs and main pages, following the llms.txt convention | | [/llms-full.txt](/llms-full.txt) | The full docs as Markdown | | `/en/docs/.md` | The Markdown version of each docs page | ## Notes - An MCP token is a secret: paste it into your client's configuration, never into a public chat or a commit. - The agent can only read approved metrics; it cannot read raw tables. --- # Reports and alerts > Send scheduled reports and threshold, change or anomaly alerts on your metrics to Telegram, Slack, Microsoft Teams or Google Sheets; connect notification destinations. The **Reports and alerts** page (in the **Data and connections** group) sends numbers to wherever your team already works: Telegram, Slack, Microsoft Teams or Google Sheets. You need the Analyst role or above; connecting destinations needs Admin. ## 1. Connect notification destinations Go to **Settings → Notifications**, card **Notification destinations**. | Destination | How to connect | | --- | --- | | Telegram | Enter a **Telegram destination name** (e.g. Sales team), click **Connect Telegram**, then open Telegram and press **Start** with the bot. To post into a group: add the bot to the group and send `/start `. The code expires after 15 minutes | | Slack | Open **How to create a Slack app (5 minutes)**: create the app from the ready-made manifest, install it in your Slack workspace, copy the **Bot token** (`xoxb-…`), invite the bot to the channel (`/invite @DataxLand`) and copy the **channel ID**. Enter a **Slack destination name**, the token and channel ID, then click **Connect Slack**; DataxLand sends a test message | | Microsoft Teams | Add the DataxLand app to a channel, group or private chat in Teams. Enter a **Microsoft Teams destination name**, click **Connect Microsoft Teams**, then send `@DataxLand connect ` in that conversation (expires after 15 minutes); the destination switches to **Active** on its own. See [Microsoft Teams](/en/docs/channels/teams) | | Google Sheets | Paste the **Service account key (JSON)**, choose a **Write mode**: **Overwrite** or **Append rows**, then click **Connect Google Sheets** (Small Business plan and above) | The **Delivery log** card records the latest 50 deliveries. ## 2. Scheduled reports 1. On the **Scheduled reports** tab, click **Create report**. The **Schedule a report** dialog opens; you can also open it from **Share → Schedule a report** on a dashboard. 2. Enter a **Report name** and choose the **Data period**: yesterday, last 7 days, last week or last month. 3. **Content**: **A dashboard page** or **Choose metrics**. 4. **Send to**: a connected destination. 5. **Frequency**: daily, weekly (pick the **Day of week**) or monthly (pick the **Day of month**, 1–28), plus the **Time** in the workspace time zone. 6. Click **Preview** to see the content, or **Send now** to test it. ## 3. Alerts 1. On the **Alerts** tab, click **Create alert**, or **Share → Set an alert** on a dashboard. The **Set up alert** dialog opens. 2. Choose the **Metric**, set an **Alert name** and an optional **Filter** (e.g. one channel). 3. **Period**: daily, weekly or monthly. 4. **Condition**: - **Crosses a threshold**: e.g. return rate above 8%; - **Changes vs previous period**: e.g. revenue down more than 20%; - **Anomaly**: drifts away from its usual range; tune the **Sensitivity** and tick **Alert in both directions** to be told about rises as well as drops. 5. **Wait between alerts (hours)**: 24 by default. 6. Click **Test run** to try it against the current numbers. Alerts are checked after every data refresh, at most once per period. The **Suggestions** tab proposes common alerts; click **Turn on** or **Customize**. The **History** tab records what was sent. ## Limits by plan | Plan | Alerts | Reports | Report frequency | Destinations | | --- | --- | --- | --- | --- | | Free | 0 | 1 | Weekly | Telegram, Slack, Teams | | Starter | 5 | 20 | Daily, weekly, monthly | Telegram, Slack, Teams | | Small Business and above | Unlimited | Unlimited | Any frequency | Telegram, Slack, Teams, Google Sheets | ## Ask Si in your chat channel Reports go one way. To ask Si questions right in Slack, Teams or Telegram, see [Slack](/en/docs/channels/slack), [Microsoft Teams](/en/docs/channels/teams) and [Telegram](/en/docs/channels/telegram). ## Related - [Plans and quotas](/en/docs/billing/quotas) - [Metrics and the semantic layer](/en/docs/metrics) - [Alerts and reports feature page](/en/platform/alerts-reports) --- # Architecture > How data flows from your sources through three layers into each workspace's own warehouse; build, check and publish; and how dashboards, Si and MCP read numbers through one metric gateway. ## Data flow 1. **Ingest**: source data lands in the raw layer, as is; DataxLand never edits or filters your original data. Personal-data columns are hashed right here unless you allow the original values to be kept. 2. **Transform**: each source table becomes a model that keeps the original column names, then is mapped onto the industry's standard model (orders, order lines, products, fees, returns, ads and so on) using the mapping you approved. 3. **Metric models**: the tables that serve the metrics of each industry × department pack. ## One build Every build (after an approval, or on a refresh) runs these steps: open the build store, ingest, generate models, transform, run quality checks, reconcile numbers, publish. Each step can be re-run safely, and each workspace only has one run at a time. If a blocking check fails or the numbers don't reconcile, nothing is published. See [Checked numbers](/en/docs/data-quality). ## The warehouse Each workspace has its own warehouse: Parquet files on object storage, a table catalogue per workspace, and storage keys used only for that workspace. A build writes into its run's build store; dashboards, Si and MCP only read the published version. ## One metric definition Dashboards, Si, reports, alerts and MCP get numbers only through **one metric gateway** on top of the semantic layer. There is no SQL in the interface, in dashboard files or in Si's tools. See [Metrics and the semantic layer](/en/docs/metrics). ## Si proposes, people approve Si reads masked samples and proposes a mapping; DataxLand generates the data model from the plan you approve. Nothing is built until the workspace is approved. See [Si](/en/docs/si). ## One tool set everywhere Si in the app; Si in Slack, Telegram and Microsoft Teams; and the [MCP server](/en/docs/mcp) all use the same read-only tool set. The tools only write audit logs and drafts awaiting approval (metric proposals, pinned tiles). ## Related - [Security and privacy](/en/docs/security-privacy) - [Sync modes and refresh schedules](/en/docs/concepts/sync-modes) - [Platform](/en/platform) --- # Connect data > The sources DataxLand accepts — Excel files, Shopee, TikTok Shop and Lazada, PostgreSQL with CDC, BigQuery, custom REST APIs and the connector library — and how to add one. Data from every source is **copied into the workspace's own warehouse**; dashboards never query your source directly. ## Source types | Type | How it connects | Notes | | --- | --- | --- | | Excel file (.xlsx) | Upload; one sheet per table plus a `data_dictionary` sheet | Up to 50 MB, 200,000 rows per sheet | | PostgreSQL | Read-only credentials | Full, incremental or CDC (logical replication) | | BigQuery | Service account key | Incremental; a scan limit (default 2 GB) caps query cost | | Shopee, TikTok Shop, Lazada | Sign in on the marketplace's page (OAuth) | No password is shared; last 90 days by default | | Any REST API returning JSON | Base URL, auth, endpoints, pagination | GET, POST or GraphQL; preview before adding | | Ads, CRM, payments, analytics… | 560+ connectors in the library | Built on the open-source Airbyte protocol | The **Free** plan accepts one Excel file. Paid plans accept every source type and scheduled refreshes. ## The `data_dictionary` sheet | Column | Required | Content | | --- | --- | --- | | `table_name` | Yes | Sheet name | | `column_name` | Yes | Column name; `*` describes the whole table | | `data_type` | Yes | Type in the source system, e.g. `VARCHAR(50)`, `DATE` | | `description` | Yes | What the column means | | `key` | No | `PK`, `FK` or `PK, FK` | | `references` | No | Referenced column, e.g. `products.sku` | | `pii` | No | `Y` for personal data; always masked | Without the sheet DataxLand still reads the file and infers types and meaning, with a warning. ## Add a source to an existing workspace 1. Open **Data sources**. You need the Admin or Owner role. 2. Click **Add source**. 3. Search in **Search connectors**, click **Select** on one or more connectors, then **Continue**. 4. Fill in each form and set **Source name** (lowercase letters, digits and underscores, starting with a letter, up to 16 characters). 5. Click **Test connection** until it shows **Connected**. 6. On **Review before adding**, click **Add N sources**. Marketplaces are connected last, on the marketplace's own page. 7. You confirm the personal-data columns again and Si proposes an updated mapping; the current dashboard stays available meanwhile. A workspace holds up to 8 sources (Starter plan: 3). ## Sync modes | Mode | What it does | Available for | | --- | --- | --- | | **Full** | Re-reads the whole table each refresh | Every source | | **Incremental** | Reads rows whose cursor column is newer, merged by primary key; does not see deletes | PostgreSQL, BigQuery, marketplaces, connectors | | **CDC (log-based)** | Reads the write-ahead log, sees updates and deletes | PostgreSQL | For CDC, click **Check CDC requirements** on the source page. It checks `wal_level = logical` (RDS/Aurora: `rds.logical_replication = 1`; Cloud SQL: `cloudsql.logical_decoding = on`), the REPLICATION privilege, a free replication slot, a primary key or `REPLICA IDENTITY FULL` on each table, and permission to create a publication. Set the refresh schedule in **Data refresh schedule**: every 15 or 30 minutes (only when every source is incremental or CDC; Small Business plan and above), hourly (Starter and above), daily, weekly or monthly. ## Passwords and personal data Password fields are encrypted at rest and never shown again. Personal-data columns are masked before reaching Si's prompt and hashed in the warehouse. See [Security and privacy](/en/docs/security-privacy). ## Related - [Quickstart](/en/docs/quickstart) - [Ask Si in the app](/en/docs/ask/app) - [Connector catalogue](/en/connectors) --- # Verified numbers > Data quality checks after every build, reconciliation against the source before publishing, the data health page and how DataxLand hides a metric when the numbers make no sense. ## Checks after every build Every build runs a set of data checks: unique keys, no empty values, relationships between tables, valid values. Each check has a level of **Blocking** or **Warning**: - **Warning**: the dashboard is still published; the failing rows are recorded so you can fix them at the source. - **Blocking**: the build is not published. Dashboards keep showing the previous published version (if there is one). A failing test does not break the build: results are stored per test, together with the source rows that failed. ## The data health page Many packs include a **Data health** page in the **Data and connections** group. The **Data quality checks** tile shows the total number of checks, how many failed and how many of those are blocking; each check reads **Passed**, **Failed** or **Couldn't run**. ## Reconciliation before publishing Before the **Publish** step, DataxLand compares a few key totals (order count, gross revenue) between the loaded data and the built warehouse. If they differ, the build stops and nothing wrong gets published; the progress view shows which step failed. ## Hidden when the numbers make no sense When the data produces an impossible number, for example general-ledger debits and credits that do not balance, the affected metric is hidden for now with a reason ("Can't be calculated yet: …") instead of showing a wrong figure. In the **Approve and build** step, the **Metrics not available yet** section lists these metrics; they do not affect any other metric. ## Build warehouse and published warehouse A build writes to its own warehouse for that run; dashboards, Si and MCP only read the published warehouse. You never see numbers from a build that is still running. ## "Incomplete" tiles On a dashboard, a tile is labelled **Incomplete** when the data coverage of its metric is below 100%; hover over the label to see the percentage. That number may be off from reality. The **Data as of** line shows the latest date with data. A tile shows **Filters not applied** when a page filter does not fit that metric. ## Related - [Metrics and the semantic layer](/en/docs/metrics) - [Review the proposal and build](/en/docs/review/mapping) - [Verified numbers on the platform page](/en/platform/data-quality) --- # FAQ and troubleshooting > How to fix the most common problems when uploading Excel, connecting sources, reviewing, building, asking Si, linking Slack or Telegram, using MCP and hitting plan limits. ## Data and sources **My Excel file was rejected.** Check that it is really `.xlsx` (not `.xls` or `.csv`), no larger than 50 MB, at most 200,000 rows per sheet, with no blank cells in row 1 and no two columns with the same name. The error message names the sheet. See [Excel files](/en/docs/sources/excel). **Is it a problem if the `data_dictionary` sheet is missing?** No. DataxLand still reads the file and infers column types and meanings from the data; Si will just ask more questions. If you do include the sheet, it must have the `table_name`, `column_name`, `data_type` and `description` columns. **I can't pick PostgreSQL, BigQuery or a connector.** The Free plan only accepts one Excel file. Upgrade to Starter or above. See [Plans and quotas](/en/docs/billing/quotas). **A marketplace shows "Contact us to enable" (the server has no app keys for it).** That marketplace connection is not set up on this server. In the meantime, use the marketplace's export with [Excel files](/en/docs/sources/excel). **Test connection says "Couldn't connect".** Check the host, port, user, password and SSL; whether the database blocks our IP; and, for connectors, that the API key is still valid and has enough permissions. **CDC shows "Not passed".** Fix each item using the table on the [PostgreSQL](/en/docs/sources/postgres#cdc) page, then click **Check CDC requirements** again. **My 15- or 30-minute schedule doesn't run.** These two frequencies need the Small Business plan or above, and every source must sync incrementally or with CDC. A schedule your plan doesn't include is skipped, with the reason shown. ## Review and build **I can't see the Approve button.** Approving needs the Admin or Owner role. **I can't approve: "Every row needs a standard status before approval".** Open **Review proposal → Statuses** and pick a standard status for every status value in your source. **The build is "Blocked".** A blocking check failed, or the built numbers don't match the source. Dashboards keep showing the previously published version. See [Checked numbers](/en/docs/data-quality), fix the source data and refresh. **A metric is missing from the dashboard.** Look at the **Metrics not available yet** section in the **Approve and build** step: usually data is missing (for example no cost of goods yet) or an implausible number has been hidden for now. ## Asking Si **Si says "Couldn't answer this question".** The metric it needs doesn't exist yet, or the question is unclear. Be more specific (metric, period, breakdown), check the [metric handbook](/en/docs/metrics), or create a [workspace metric](/en/docs/metrics/workspace-metrics). **Si misunderstands a term your business uses.** Add a **Term** entry on the [Knowledge](/en/docs/metrics/knowledge) page and approve it. **I can't see Ask Si.** The Viewer role cannot ask Si; ask the Owner to change your role to Analyst. **"This month's Si questions are used up".** Wait for the next period, buy 500 more questions, or upgrade. Dashboards and reports keep running. ## Slack, Telegram, MCP **The bot doesn't answer in a group.** In groups, the bot only reads `/ask`, messages that mention it and replies to its own messages. The group must be bound to a workspace with `/ws`, and the person asking must have linked their account. See [Telegram](/en/docs/channels/telegram) and [Slack](/en/docs/channels/slack). **My link code is rejected.** Codes are single-use, expire after 10 minutes and are only accepted in a private chat with the bot. Create a new code. **I can't create an MCP token.** MCP needs the Small Business plan or above and the Admin role. A token is shown only once; if you lose it, revoke it and create a new one. See [MCP server](/en/docs/mcp). ## Account **I lost the phone with my 2FA app.** Sign in with one of your 10 recovery codes, then set up 2FA again. See [Two-factor authentication](/en/docs/workspace/2fa). **I deleted a workspace by mistake.** The Owner can restore it within 7 days from **Account → Workspaces pending deletion → Restore**. ## Related - [Glossary](/en/docs/glossary) - [Quickstart](/en/docs/quickstart) - [Contact](/en/contact) --- # Glossary > What the terms used in DataxLand mean — workspace, Si, proposal, mapping, semantic layer, confirmation level, build, publish, CDC, PII, MCP and more. | Term | Meaning | | --- | --- | | Approved version | The version of a proposal an Admin has approved; builds run on this version | | Build | One rebuild of the warehouse from your sources and the approved version: ingest, transform, check, publish | | CDC (log-based sync) | PostgreSQL sync that reads the change log, so it sees updated and deleted rows too. See [Sync modes](/en/docs/concepts/sync-modes) | | Connector | A plug-in that connects a source application. See [Connector library](/en/docs/sources/connector-library) | | Copilot | Former name of Si's context analysis; the app no longer uses it | | Data type | The industry and department Si chooses for the workspace | | Deep thinking | A mode where Si works through several analysis steps; slower, and counts as 3 questions | | Dimension | A way to break a number down: channel, product, day and so on | | Incremental | Sync that only reads new or changed rows, using a cursor column | | Industry × department pack | A set of standard models, metrics and dashboards for one industry and one department | | Knowledge | Instructions, glossary terms and events that help Si understand your business. See [Knowledge](/en/docs/metrics/knowledge) | | Mapping | Which source column feeds which field of the standard model (order ID, date, amount, fee…). Si proposes, people approve | | MCP | Model Context Protocol: the standard for outside AI agents to call tools. See [MCP server](/en/docs/mcp) | | MCP token | An expiring key that lets an outside agent read metrics; shown only once | | Metric | A number with a definition, unit and version: net revenue, profit after fees and so on | | Notification destination | Where reports and alerts are delivered: Telegram, Slack, Microsoft Teams, Google Sheets | | PII | Personal data (name, phone, email, address). Masked from Si and hashed in the warehouse | | Proposal | What Si drafts for you: the business model, mapping, statuses, questions, metrics and layout | | Publish | The last step of a build: the new version replaces the old one for dashboards, Si and MCP | | Published warehouse | The version of the warehouse that dashboards, Si and MCP are reading | | Quota | Your plan's limits: sources, storage, Si questions and more. See [Plans and quotas](/en/docs/billing/quotas) | | Semantic layer | The description of tables, relationships, dimensions and filters that turns every question and dashboard tile into the right query | | Si | DataxLand's AI data assistant: Si's context analysis and Si's question answering. See [Si](/en/docs/si) | | Soft limit | When you reach a plan limit, only creating more is blocked; viewing never is | | Standard, Approved, Unconfirmed | The three [confirmation levels](/en/docs/metrics) of a number: from a pack, an approved workspace metric, or an exploratory answer | | Standard model | The shared tables of an industry (orders, order lines, products, fees, returns…) your source data is mapped onto | | Workspace | The unit that holds data, members and a plan. See [Workspaces](/en/docs/concepts/workspace) | | Workspace metric | A metric your workspace defines itself, with ID `ws.`, checked against the data before it is switched on | | Workspace page | A page of tiles you pick, private or shared. See [Workspace pages](/en/docs/dashboards/pages) | --- # DataxLand documentation > Get started with DataxLand — connect data, review Si's proposal, read verified dashboards and ask Si questions. DataxLand is the AI data team for companies without one: it connects any business data (Excel, databases and 500+ sources) for any industry and team, builds verified dashboards on its own, and lets you ask **Si**, the AI data assistant. Si works out what your data means and asks when something is unclear; you approve before anything is built. ## Where to start | You want to | Page | | --- | --- | | See what DataxLand does in five minutes, then get your first dashboard | [Quickstart](/en/docs/quickstart) | | Understand workspaces, their states and roles | [Workspace](/en/docs/concepts/workspace) | | Connect Excel, a database, an API, a marketplace or a connector | [Connect data](/en/docs/connect-data) | | Review how Si understood your data before building | [Review and build](/en/docs/review/mapping) | | Ask Si in the app | [Ask Si in the app](/en/docs/ask/app) | | Know exactly how a number is calculated | [Metrics and the semantic layer](/en/docs/metrics) | | Get reports and alerts, or ask Si in Slack, Teams or Telegram | [Reports and alerts](/en/docs/alerts-reports) | | Connect Claude, Cursor or your own agent | [MCP server](/en/docs/mcp) | | Invite colleagues and turn on 2FA | [Members and roles](/en/docs/workspace/members) | | Set up SSO, custom roles and row-level access | [SSO](/en/docs/workspace/sso) · [Roles](/en/docs/workspace/roles) · [Row-level access](/en/docs/workspace/data-access) | | Embed a dashboard in your own app or portal | [Embed a dashboard](/en/docs/dashboards/embed) | | Run DataxLand on your own infrastructure | [Self-hosting](/en/docs/self-host) | | Check your plan's limits | [Plans and quotas](/en/docs/billing/quotas) | Screen labels are quoted exactly as they appear in the app. ## Three data layers Data flows through three layers: **ingest** (kept exactly as received), **transform** (mapped to your industry's standard model) and **metric modeling** (metrics with a definition and a version). Si proposes how to read and map your data; you approve before anything is built. Details in [Architecture](/en/docs/architecture). ## Something not working? See [FAQ and troubleshooting](/en/docs/faq) and the [Glossary](/en/docs/glossary). ## For AI agents Every docs page has a Markdown version: add `.md` to the URL (for example [/en/docs/mcp.md](/en/docs/mcp.md)). The index for agents is [/llms.txt](/llms.txt); the full text is [/llms-full.txt](/llms-full.txt). See [Set up with an AI agent](/en/docs/agent-setup). --- # MCP server > Connect Claude Desktop, Claude Code, Cursor or your own AI agent to a workspace's approved metrics over the Model Context Protocol — tokens, scopes, client config and tools. DataxLand runs a [Model Context Protocol](https://modelcontextprotocol.io) server. External agents use **the same tools as Si**: metrics, dimensions, filters, periods and comparisons through the semantic layer. There is no free-form SQL tool by default; a token granted the extra `explore:run` scope gets the exploration sandbox (results are always Unconfirmed, see [Si writes and runs SQL/Python](/en/docs/ask/sandbox)). ## 1. Create a token MCP needs the **Small Business** plan or above and the Admin role or above. 1. Go to **Settings → Integrations**, section **MCP tokens**. 2. Under **Create token**, enter a **Label**. 3. **Permissions**: **metrics:read** to read metrics; add **ops:read** if the agent should see build status (it never returns data values). 4. **Workspace**: the workspace the token can read. The Enterprise plan can give one token several workspaces. 5. **Expires after (days)**: default 90, up to 365. 6. Click **Create token**. The token (prefix `dxp_`) is shown **once**, so click **Copy**. DataxLand stores only its hash. **Created tokens** lists tokens as **Active**, **Expired** or **Revoked**. **Revoke** revokes immediately. ## 2. Configure your client The server speaks Streamable HTTP at the path `/mcp` and authenticates with `Authorization: Bearer `. The URL below is the hosted service; a self-hosted deployment uses its own MCP server address. ### Cursor `~/.cursor/mcp.json` (or `.cursor/mcp.json` in a project — never commit the token): ```json { "mcpServers": { "dataxland": { "url": "https://app.dataxland.com/mcp", "headers": { "Authorization": "Bearer " } } } } ``` ### Claude Code ```bash claude mcp add --transport http dataxland https://app.dataxland.com/mcp \ --header "Authorization: Bearer " ``` ### Claude Desktop Claude Desktop reaches a remote server with a header through the `mcp-remote` bridge (requires Node.js). Open **Settings → Developer → Edit Config** and add: ```json { "mcpServers": { "dataxland": { "command": "npx", "args": ["-y", "mcp-remote", "https://app.dataxland.com/mcp", "--header", "Authorization:${DX_MCP_TOKEN}"], "env": { "DX_MCP_TOKEN": "Bearer " } } } } ``` Restart Claude Desktop. ## 3. Try it Ask your agent: "Using DataxLand, list the workspace metrics", then "Profit after fees last month by channel". ## Tools | Scope | Tools | | --- | --- | | metrics:read | `list_metrics`, `describe_metric`, `query_metric`, `query_semantic`, `get_semantic_model`, `explain_change`, `get_business_model`, `search_knowledge` | | ops:read | `get_health`, `list_runs`, `get_run`, `list_metric_requests` | A multi-workspace token (Enterprise plan) also gets `list_tenants`, and every tool takes a `tenant` parameter. ## Safety and limits - Every call is logged with its token and tool. - A multi-workspace token names the workspace in each call; the server checks the token is allowed for it. - Operations tools never return data cell values; no tool returns buyers' personal data. - At most 60 calls per minute per token and 120 per minute per user. - Treat the token as a secret: do not paste it into public chats or commit it. ## Related - [Ask Si in the app](/en/docs/ask/app) - [API overview](/en/docs/api/overview) - [Security and privacy](/en/docs/security-privacy) --- # Quickstart > From sign-up to the sample workspace, your first dashboard on your own data and your first question to Si. This page goes round the whole loop: try it on sample data, then do it again with yours. Screen labels are quoted as you see them in the app. In the app, both the context analysis and the Q&A screen **Ask Si** are Si. ## 1. Sign up (2 minutes) 1. Open [app.dataxland.com/signup](https://app.dataxland.com/signup) and sign up with email or Google. 2. Click the verification link in the email. The **Getting started** box counts the remaining steps. ## 2. Try the sample workspace (3 minutes) On the welcome screen, pick **Your industry** and **Sample dataset**, then click **Open sample workspace**. The dashboard is pre-built on simulated data and carries a **Demo workspace** banner. A sample workspace does not take a workspace slot of your plan; delete it at any time with **Delete demo workspace**. ## 3. Create a workspace with your data (5 minutes) 1. Click **Create my workspace**, or open `/new`. 2. Enter a **Workspace name**. 3. Pick a source. The Free plan uses **Excel file**: click **Upload file** and choose an `.xlsx` file of up to 50 MB, one sheet per table, plus a `data_dictionary` sheet describing the columns. See [Connect data](/en/docs/connect-data). 4. Click **Create workspace and read data**. ## 4. Choose columns to mask (2 minutes) The step **Choose data and personal data** lists columns that look like personal data. Keep names, phone numbers, emails and addresses masked; tick the consent to send a masked sample (up to 1,000 rows) and click **Confirm and let Si analyse**. ## 5. Clarify and approve (10–20 minutes) Si reads the masked sample and drafts a proposal, usually in 1–3 minutes. Then: 1. **Clarify and review**: read how Si understood your data (any domain: sales, HR, finance, operations…), then pick answers under **Si needs you to choose**. Si's recommended option is preselected; choose **Other** to type your own. Click **Save and continue**. 2. **Approve and build**: review what Si will build (metrics with how each is computed, dashboard pages), your answers and the assumptions, then click **Approve and build**. Nothing is built until the workspace is approved. ## 6. Read the dashboard The build runs in the background: load, transform, quality checks, publish. When the status is **Ready**, click **Open the dashboard**. Change the period with the date picker (default: last 90 days) and add filters with **Add filter**. Click **Why?** on a number to see what drove the change. ## 7. Ask Si Open **Ask Si** in the sidebar, type a question, for example "How did revenue and profit do last month?", and click **Ask**. Every answer has a **Sources** section and a confirmation level. See [Ask Si in the app](/en/docs/ask/app). ## Related - [Connect data](/en/docs/connect-data) - [Security and privacy](/en/docs/security-privacy) - [Pricing](/en/pricing) --- # Security and privacy > Masking and hashing of personal data, per-workspace storage, encrypted secrets, roles and 2FA, encrypted backups, the OWASP ASVS level 1 target, export and deletion. A technical summary. Binding terms are in the [privacy policy](/en/privacy) and the [data processing agreement](/en/dpa). ## Personal data - Columns marked as personal data are **masked before they reach Si's prompt**. - Values are **hashed** (SHA-256 with a per-workspace salt) as soon as they are loaded; the published warehouse never contains the salt. Keeping original values is an opt-in, off by default. - No API, Si answer or MCP tool returns buyers' personal data. - Si only reads a masked sample of up to 1,000 rows, and only with your consent. ## Per-workspace isolation - Each workspace has its own warehouse: Parquet files under their own storage prefix, its own table catalogue and **its own storage keys**, which can only read that workspace's prefix. - Dashboards, Si and MCP read only the published copy of the right workspace; every request checks the caller's access to it. ## Secrets and passwords - Source passwords, service account keys, Slack tokens and 2FA secrets are **encrypted at rest** and never shown again; the encryption key can be rotated. - Login passwords are hashed with Argon2id. - MCP tokens are stored only as hashes, expire and can be revoked. ## Access - Four roles per workspace: Owner, Admin, Analyst, Viewer. - Two-factor authentication with an authenticator app (TOTP) and 10 recovery codes; the Owner can **require 2FA** for Owners and Admins. - Short sessions (15-minute access tokens), sign out one device or all; login is locked for 15 minutes after 5 failures. - A security log per workspace; every Si and MCP tool call is recorded. ## Web application - Security headers: a per-request Content Security Policy, no framing, HSTS in production. - Rate limits on login, questions to Si and MCP. - Controls target **OWASP ASVS 4.0.3 level 1**; the checklist is tracked internally and some items (such as production TLS configuration) are still being completed. This is a target, not a certification. ## Backups - Automatic daily backups, keeping 7 daily, 4 weekly and 6 monthly copies. - Backups are **encrypted before they leave the server** (AES-256-GCM) with a separate key, then stored on object storage with encryption, versioning and object lock. - Targets: at most 24 hours of data loss, recovery within 4 hours. ## Export and deletion You can export all of a workspace's data (Parquet, CSV for tables up to 100,000 rows, definitions as JSON), download your personal data, delete a workspace (restorable for 7 days) or delete your account at any time. Backups expire after at most 6 months. ## Reporting a vulnerability Email security@dataxland.com. ## Related - [MCP server](/en/docs/mcp) - [API overview](/en/docs/api/overview) - [Connect data](/en/docs/connect-data) --- # Si: context analysis and Q&A > Si is DataxLand's AI data assistant — it proposes how to read and map your data for you to approve, and answers questions with approved metrics. **Si** is one assistant that does two jobs: **Si context analysis** (reads your data and proposes mappings for a person to approve) and **Si Q&A** (answers questions in the app, in Slack, Microsoft Teams and Telegram, and over MCP). Everywhere in the app it is called Si: the context analysis (for example the **Ask Si to propose** button), the **Ask Si** Q&A screen and the **Ask Si** panel on the right of a dashboard. Where the two jobs need telling apart (admin pages, costs), they appear as **Si · Context analysis** and **Si · Q&A**. Older names such as Copilot, "Ask AI" or AI Agent no longer appear on screen. ## Si context analysis When you connect a source, Si reads the table structure, the column descriptions and a sample of the data **with personal data masked** (up to 1,000 rows, only with your consent), then works through the steps you see in the **Si is analysing…** panel: 1. Read the table structure and the masked sample 2. Investigate the data 3. Pick a suitable analytics template 4. Understand the business model 5. Map columns to the standard model 6. Normalise values: statuses, channels, fee types 7. Choose the metrics that can be computed 8. Write the questions you need to confirm 9. Propose the menu layout and home page 10. Save the proposal While investigating, Si may run **read-only** queries on the masked sample or on the source database, within limits on the number of queries and their cost; a query over those limits waits for a technical person to confirm it. The final data model is generated by DataxLand from the plan you approve; queries Si wrote never go into the build. You help Si understand your data better with the `data_dictionary` sheet, the **Data context for Si** box (notes, description documents) and the [Knowledge](/en/docs/metrics/knowledge) page. ## Si proposes, people approve Mappings, new workspace metrics and the semantic model are all **drafts** until an Admin or the Owner approves them. Nothing is built until the workspace is **Approved**. Tiles Si pins to a page carry a **Draft** label until you click **Save**. See [Review the proposal and build](/en/docs/review/mapping). ## Si Q&A Si answers questions in the [app](/en/docs/ask/app), in [Slack](/en/docs/channels/slack), [Microsoft Teams](/en/docs/channels/teams) and [Telegram](/en/docs/channels/telegram), and over [MCP](/en/docs/mcp). For official numbers Si **reads metrics through the semantic layer**: your question is translated into metrics, dimensions, filters, a period and a comparison, and DataxLand's engine builds the query from the approved definitions. Si never runs model-written SQL against those numbers. For exploratory questions beyond the existing metrics (medians, correlations, ad-hoc joins, custom charts), Si can write and run SQL or Python in an isolated [exploration sandbox](/en/docs/ask/sandbox); those results are always labelled Unconfirmed. ### Confidence levels | Level | Meaning | | --- | --- | | Standard | A standard metric of the industry × department pack | | Approved | Your workspace's own metric, checked against data and approved | | Unconfirmed | An exploratory answer on the approved model; check it before using it as an official number | See [Metrics and the semantic layer](/en/docs/metrics). ## Personal data Personal-data columns are masked before anything reaches a prompt and hashed in the warehouse. Si never returns buyers' personal data. See [Security and privacy](/en/docs/security-privacy). ## Related - [Answer Si's questions](/en/docs/review/questions) - [Number inspector](/en/docs/ask/inspector) - [Si on the platform page](/en/platform/si) --- # HTTP API overview > Conventions of the DataxLand HTTP API — Bearer authentication, choosing a workspace, the error shape, rate limits (429, Retry-After), quotas (402) and resource groups. The DataxLand HTTP API is the API the web app uses; everything in the app goes through it. There are **no separate API keys** for machine-to-machine integration yet: to let an AI agent or an external tool read metrics, use the [MCP server](/en/docs/mcp) with an expiring, revocable token. ## Base path and versioning - Every path starts with `/v1`. From the browser the app calls `/api/v1/…` on its own domain. - Responses are UTF-8 JSON. Dates are `YYYY-MM-DD`; timestamps are ISO 8601 in UTC. Business dates (periods, "data as of") follow the workspace's time zone. - The UI says **workspace**; the API says `tenant`. ## Authentication 1. `POST /v1/auth/login` returns an access token (JWT) valid for 15 minutes. 2. Send it with every request: `Authorization: Bearer `. 3. Refresh with `POST /v1/auth/refresh`, using the `dx_refresh` session cookie (HttpOnly) and the header `X-DX-CSRF: 1`. Missing, invalid or expired token: `401`. Missing role in the workspace: `403`. Accounts with 2FA enter their code at login. ## Choosing a workspace - Paths `/v1/tenants/{id}/…` use `{id}`. - Metric, dashboard and ask endpoints (`/v1/metrics…`, `/v1/dashboards…`, `/v1/ask`) use the header `X-DX-Tenant: `. A workspace the user does not belong to: `403`. ## Errors Every error has the same shape: ```json { "detail": { "code": "quota_exceeded", "message": "…", "details": null } } ``` | HTTP | When | | --- | --- | | 400 | Bad parameters; invalid Excel file | | 401 | Not signed in, or token expired | | 402 | Plan quota reached, `code = quota_exceeded` | | 403 | Not allowed, or missing CSRF header | | 404 | Not found | | 409 | State conflict, e.g. the workspace already has a run in progress | | 413 | `too_large`: request body too big (multipart over 110 MB, JSON over 5 MB) | | 422 | Invalid approval; `details` lists the errors | | 429 | `rate_limited` | `message` is human-readable and safe to show to users. ## Rate limits (429) Over a limit the API returns `429` with `code = "rate_limited"`, a **`Retry-After`** header (seconds) and `details.retry_after`. Wait that long before retrying; do not retry in a tight loop. | Group | Limit | | --- | --- | | Login | 20 per minute per IP | | Sign-up | 10 per 10 minutes per IP | | Asking Si (`POST /ask`, messages in a session) | 20 per minute per user, 60 per minute per workspace | | File uploads | 30 per 10 minutes per user | | MCP | 60 per minute per token, 120 per minute per user | ## Quotas (402) Creating something beyond the plan's quota returns `402 quota_exceeded`; reading is never blocked. ## Resource groups Auth, account and members · workspaces (create, status, approve, build, settings) · sources (connectors, marketplace OAuth, refresh schedules, personal-data confirmation) · metrics and dashboards · semantic layer (model, semantic queries, "why" analysis, workspace metrics and pages) · questions to Si, history, knowledge · notifications (destinations, scheduled reports, alerts, chat Q&A) · MCP tokens · plan usage and add-ons · data rights (workspace export, personal export, deletion). The interactive API docs (`/docs`) are disabled in production. ## Related - [MCP server](/en/docs/mcp) - [Security and privacy](/en/docs/security-privacy) --- # Ask Si in the app > Ask Si in plain language on the Ask Si screen or in the dashboard's Ask Si panel; read the source and confirmation level, edit how the question was understood, use deep thinking. The **Ask Si** screen (under **Ask and explore**) is where you ask Si. Si only uses metrics from the **Metric handbook**, and every answer has a **Sources** section. You need the Analyst role or above. ## Ask 1. Type your question or click one of the **Suggested questions**. 2. Click **Ask**. Good questions name the metric, the period and the breakdown: | Instead of | Ask | | --- | --- | | "How are sales?" | "Net revenue last month by channel" | | "Profit?" | "Profit after fees for the last 28 days vs the previous period" | | "Best products?" | "Top 10 products by gross profit this month" | ## Read the answer - **Sources**: the metric and version used, the period, and the date the data runs to. - **Confirmation level**: **Standard** (a metric of the industry × department pack), **Approved** (a workspace metric that was checked and approved) or **Unconfirmed** (an exploratory answer; check it before using it as an official number). - **Tools called**: the lookups Si made. - When the metric does not exist or data is missing, Si says **Couldn't answer this question** instead of guessing. For standard numbers, Si does not write SQL: the question is translated into metric, dimension, filter, period and comparison, and DataxLand's engine builds the query from approved definitions. Exploratory questions beyond the metric library (medians, correlations, custom joins) run as SQL or Python in the [exploration sandbox](/en/docs/ask/sandbox) and are always labelled Unconfirmed. ## Answer language Si answers in the language you ask in: ask in English and you get an English answer with a **Source** line; ask in Vietnamese, with or without accents, and you get Vietnamese. When a question is too short to tell (for example "GMV?"), Si follows the language of your previous question in the conversation, then the workspace's **Number and date format** setting ([time zone, currency and format](/en/docs/workspace/region)): an English format means English answers. Ask "answer in Vietnamese" or "answer in English" to switch. Numbers and money keep the workspace format, so they match your dashboards. ## Edit how the question was understood Under the answer, **How the question was understood** lists chips for metric, dimension, filter, period, comparison and top-N. Click one, change it and click **Run again**. The re-run goes straight to the semantic layer without asking the AI again. From the result you can **Pin to page**. ## Deep thinking Turn on **Deep thinking** for multi-step questions ("why did profit drop this month, which channel, which product?"). It is slower, can take about a minute and counts as 3 questions; **Reasoning** shows the steps. Not on the Free plan. ## Ask about a dashboard page On a dashboard, click **Ask Si** in the top bar. Si knows which page you are on and suggests "Summarize this page" or "Anything unusual?". Clicking **Why?** on a number opens the inspector, which explains the change by formula and by dimension, computed by the engine, not written by the AI. ## Quotas Each question counts towards the plan's monthly AI questions (Free 30, Starter 300, Small Business 1,500). When they run out, asking pauses until the next period; dashboards and reports keep running. ## Related - [Ask Si in Slack](/en/docs/channels/slack) · [Telegram](/en/docs/channels/telegram) - [MCP server](/en/docs/mcp) - [Quickstart](/en/docs/quickstart) --- # Number inspector > Open the inspector of a tile or a point on a chart to see the summary, facts, breakdown, why it changed versus the previous period and the SQL that ran. Every number on a dashboard can be opened to see where it comes from. The explanation is computed by the metric engine from the definition, not written by AI. ## Open the inspector - Click **Details** on a tile, or click a bar or point on a chart. - Click **Why?** on a number tile to jump straight to the **Why it changed** tab. ## Tabs | Tab | Shows | | --- | --- | | Summary | The value, period, filters applied and the comparison with the previous period | | Facts | The key facts of the selected point | | Breakdown | The number split by one dimension (channel, product…) | | Why it changed | How much each part contributed to the change | | SQL | The query the metric engine ran (you can **Copy** it) | ## Why it changed Choose **Vs. previous period** (why it rose or fell) or **Why it's at this level**. The tab explains it in several ways: - **By formula**: the metric split into its components (for example profit after fees = net revenue − cost of goods − fees) and which component drove the change; - **By formula tree**: the same idea, several levels deep; - **Pulling down most** / **Pushing up most**: the values of a dimension (channel, product) that contributed most; - **Notable two-dimension combinations**: for example one product on one channel; - a table of **This period**, **Comparison period** and **Change**. ## Follow up, pin - **Ask Si about this**: opens the Ask Si panel with the selected point as context. - **Pin to page**: see [Dashboards and pinning to a page](/en/docs/dashboards/pin). - **Clear selection** closes it. Si uses the same explanation when you ask "why", whether in the app, Slack, Telegram or over MCP. ## Related - [Ask Si in the app](/en/docs/ask/app) - [Metrics and the semantic layer](/en/docs/metrics) - [Verified numbers](/en/docs/data-quality) --- # Si writes and runs SQL/Python > For exploratory questions that go beyond the ready-made metrics (medians, percentiles, correlations, joining two tables, custom charts), Si writes SQL or Python and runs it in an isolated sandbox. Results are always Unconfirmed. Most questions are answered from **metrics** and the **semantic layer** — **Standard** or **Approved** numbers that match your dashboards. When a question goes beyond the metrics you have, Si can **write its own SQL or Python** and run it in the **exploration sandbox**. It's a tool for analysis, not a replacement for official metrics. ## When Si uses the sandbox | Question | Si uses | | --- | --- | | Revenue, profit, orders, return rate; versus last period; top N; "why did it drop" | Metrics and the semantic layer (Standard numbers) | | Median, percentiles, order-value distribution | Sandbox (SQL) | | Correlation between daily ad spend and revenue | Sandbox (SQL or Python) | | Joining two tables on a key the model doesn't have yet | Sandbox (SQL) | | Monthly cohorts, simple regression, custom charts | Sandbox (Python) | Si always tries the semantic layer first. It never uses the sandbox to recompute a metric that already exists. ## Confirmation level: always "Unconfirmed" Every number computed in the sandbox carries the **Unconfirmed** label: the code was written by Si and nobody has checked the definition yet. The answer states its confirmation level, and each run gets a card under the answer with: - the **Unconfirmed** label; - **View SQL code / View Python code** (collapsed) - read it to see how Si computed the result; - the result table (up to 100 rows), charts (up to 2) and printed output. Sandbox results **can't** be pinned as dashboard tiles and **can't** be saved as a "confirmed answer". To keep something for the long run: 1. **Save draft to knowledge** (code included) so a reviewer can read it; or 2. ask Si to **save it as a metric** — Si creates a draft metric on the semantic model, and a reviewer checks the numbers before turning it on (see [Workspace metrics](/en/docs/metrics/workspace-metrics)). ## What the sandbox can read - Only **published** data (the same version your dashboards show), the **core** and **marts** layers. No raw data (`raw`) or intermediate layers. - **No personal data**: columns such as phone numbers, emails, buyer names, hashed columns and customer identifiers are removed before the data reaches the sandbox. To count customers, Si uses the semantic layer. - A read-only copy: code can't write to the workspace's data, metrics or configuration. ## Security - Code runs in a **separate sandbox service** with no network, no access to files outside the run's temporary folder, and no keys or passwords. Each run is capped: 30 seconds, a memory limit, 200 result rows for Si. - SQL must be **a single read statement** (SELECT); statements that write, read files or change settings are rejected before they run. - Every run is recorded in the audit log: the **code** and the **number of result rows** (data values are not logged). ## Who can use it - The **Analyst**, **Admin** and **Owner** roles. The **Viewer** role can't. - The **Small Business** plan and above (see [Plans and limits](/en/docs/billing/quotas)). Each run counts as **1 extra Si question**. - Up to 4 runs per question and 20 runs per minute per person. - Web app only. Questions through Telegram, Slack or Teams don't use the sandbox. - Over MCP: only tokens granted the extra `explore:run` scope (off by default); see [MCP](/en/docs/mcp). ## FAQ **Why does a sandbox number differ from the dashboard?** Si's code may filter or group differently from the metric definition (for example, including cancelled orders). Open "view code" to see how it was computed; the official number is still the one on the dashboard. **Si says the exploration sandbox is not enabled?** Your server isn't running the sandbox service; contact your administrator (self-hosted deployments). **Si says you're out of questions?** Each run counts towards the month's Si questions; buy a 500-question pack or upgrade your plan. --- # Ask Si in Slack > Install DataxLand in Slack, link your account with a one-time code using /dataxland link, ask Si in direct messages or channels and bind a channel to a workspace. Si answers in Slack exactly as in the app: numbers, causes, confirmation level and an **Open in DataxLand** link. Available on every plan; each question counts towards the workspace's AI-question quota. Askers need the Analyst role or above. ## 1. Install and link 1. Open **Account**, card **Chat connections**, click **Connect Slack**. 2. If your Slack workspace does not have DataxLand yet, click **Install DataxLand in Slack** and allow it (once per Slack workspace). 3. Click **Create link code**. The code is single-use and expires after 10 minutes. 4. In Slack, type `/dataxland link lk_`. DataxLand replies "Linked to account…". Unlink with **Disconnect** or `/dataxland unlink`. ## 2. Ask - **Direct message** to DataxLand: send your question. - **In a channel**: mention `@DataxLand` with your question, or type `/dataxland ask `. A channel must be bound to one workspace: someone with the Admin role or above types `/dataxland ws ` in that channel. Admins unbind it in **Settings → Notifications → Q&A chats**. ## Commands The same commands as Telegram, without the leading slash, after `/dataxland` (or in a direct message): `ask`, `think` (deep thinking, counts as 3 questions), `new`, `ws`, `link`, `unlink`, `help`. ## Two different Slack apps - **DataxLand**, installed with **Install DataxLand in Slack**: for **asking Si** (this page). - **A reporting app** you create from a manifest in **Settings → Notifications** (bot token `xoxb-…` and channel ID): for **receiving scheduled reports and alerts** in a channel. They are independent; use either or both. ## Limits - Long answers are cut at about 2,900 characters with a link to the full answer. - Asking too fast returns "You're asking too fast; wait a few seconds and try again." - Si never returns buyers' personal data in chat. ## Related - [Ask Si in Telegram](/en/docs/channels/telegram) - [Ask Si in the app](/en/docs/ask/app) - [MCP server](/en/docs/mcp) --- # Microsoft Teams > Add the DataxLand app to Microsoft Teams to receive reports and alerts with charts and to ask Si in channels or private chats; link your account with a one-time code. DataxLand in Microsoft Teams does two jobs with one app: - **Scheduled reports and alerts** delivered to a channel, group chat or private chat, with charts. - **Ask Si** about your numbers: answers match the app (numbers, causes, confirmation level, an **Open in DataxLand** button) and count towards the workspace's AI-question quota. Askers need the Analyst role or above. Teams is available on every plan that includes Slack. ## 1. Add the DataxLand app to Teams , then keep asking in the thread." /> In Teams open **Apps**, search for **DataxLand** and click **Add**. If your company blocks third-party apps, ask your Teams admin to allow DataxLand (Teams admin center → Apps). To use it in a channel: open the channel → **+** (Add an app) → DataxLand. The **Chat connections** page and the new-destination dialog show an **Add DataxLand to Teams** button when the server has an app install link configured. ## 2. Link your account to ask Si 1. Open **Account**, card **Chat connections**, click **Connect Microsoft Teams**. 2. Click **Create link code**. The code is single-use and expires after 10 minutes. 3. Open a **private chat** with DataxLand in Teams and send `link lk_`. DataxLand replies "Linked to account…" and you're done. For safety, a code sent in a channel or group chat is rejected (others can see it) and is not used up. Unlink with **Chat connections → Disconnect** or by sending `unlink`. ## 3. Ask - **Private chat** with DataxLand: just type your question. - **In a channel or group chat**: mention `@DataxLand` with your question. Teams only sends DataxLand the messages that mention it; DataxLand never reads anything else. The answer goes into the question's thread, visible to everyone in the channel. A channel must be bound to one workspace: someone with the Admin role or above sends `@DataxLand ws ` in that channel. A channel already connected as a report destination (section 4) is bound automatically. Admins unbind it in **Settings → Notifications → Q&A chats**. ## 4. Receive reports and alerts in Teams 1. Go to **Settings → Notifications**, click **Add Microsoft Teams**, name the destination (e.g. "Sales channel"), then click **Connect Microsoft Teams**. 2. In the channel, group chat or private chat where DataxLand is installed, send `@DataxLand connect nd_` (the code expires after 15 minutes). 3. The destination switches to **Active**. Click **Send test** to check. Then pick this destination when you create a [scheduled report or alert](/en/docs/alerts-reports). Each message is a card with a title, the numbers and a button that opens the dashboard; the chart follows right after the card. ## Commands Type them without a leading `/`, in a private chat or after `@DataxLand`: | Command | What it does | | --- | --- | | `` | Ask about your numbers | | `think ` | Ask with deep thinking (counts as 3 questions) | | `new` | Start a new conversation | | `ws` | Show or switch workspace (in a channel: bind the channel to a workspace) | | `link`, `unlink` | Link or unlink your account | | `connect ` | Receive reports and alerts in this conversation | | `help` | How to use it | ## Limits - Long answers are cut at about 6,000 characters, with a button to open the full answer in DataxLand. - Charts larger than 1 MB can't be sent (DataxLand charts are usually a few dozen KB). - DataxLand can't post into Teams private channels; use a standard channel, a group chat or a private chat. - Asking too fast returns "You're asking too fast; wait a few seconds and try again." - Si never returns buyers' personal data in chat. ## Related - [Ask Si in Slack](/en/docs/channels/slack) - [Ask Si in Telegram](/en/docs/channels/telegram) - [Reports and alerts](/en/docs/alerts-reports) - [Members and roles](/en/docs/workspace/members) --- # Ask Si in Telegram > Link your DataxLand account to Telegram with a one-time code, ask Si in a private chat or a group, bind a group to a workspace, and use /ask, /think, /ws. Si answers in Telegram exactly as in the app: numbers, causes, confirmation level and an **Open in DataxLand** link. Available on every plan; each question counts towards the workspace's AI-question quota. Askers need the Analyst role or above. ## 1. Link your account (once) 1. Open **Account** from the user menu, card **Chat connections**, click **Connect Telegram**. 2. On **Connect a chat to your account**, click **Create link code**. The code is single-use and expires after 10 minutes. 3. Click **Open Telegram** and press **Start** with the DataxLand bot, or send the bot `/start lk_`. 4. The bot replies "Linked to account…" and you are done. Codes are only accepted in a private chat with the bot; a code posted in a group is refused (and stays usable). Unlink with **Disconnect** or `/unlink`. ## 2. Private chat Just send your question, e.g. "Revenue yesterday by channel?". If you belong to several workspaces, send `/ws` to see or switch the workspace. ## 3. Groups 1. Add the DataxLand bot to the group. 2. Someone with the Admin role or above sends `/ws ` to bind the group to a workspace. Groups already linked as a notification destination are bound automatically. 3. Linked members ask with `/ask `, by mentioning the bot, or by replying to the bot. In groups the bot only reads `/ask`, mentions and replies to its own messages — never the rest of the conversation. Admins unbind a group in **Settings → Notifications → Q&A chats**. ## Commands | Command | What it does | | --- | --- | | `/ask ` | Ask (required in groups) | | `/think ` | Ask with deep thinking (counts as 3 questions) | | `/new` | Start a new conversation | | `/ws` | Show or switch the workspace | | `/link`, `/unlink` | Link or unlink your account | | `/help` | Help | A new conversation starts after 30 minutes of silence or with `/new`. ## Limits - Long answers are cut at about 3,500 characters with a link to the full answer. - Asking too fast returns "You're asking too fast; wait a few seconds and try again." (20 questions per minute per person, 60 per minute per workspace). - Si never returns buyers' personal data in chat. ## Related - [Ask Si in Slack](/en/docs/channels/slack) - [Ask Si in the app](/en/docs/ask/app) --- # Plans and limits > The limits of each plan (workspaces, users, sources, storage, AI questions for Si, alerts, reports, MCP tokens), how to check usage, buy add-ons, and what happens when you hit a limit. Full prices and features are on the [pricing page](/en/pricing). This page explains how limits work. ## Limits by plan | Limit | Free | Starter | Small Business | | --- | --- | --- | --- | | Workspaces | 1 | 1 | 1 | | Users | 1 | 5 | Unlimited | | Sources per workspace | 1 (Excel only) | 3 | 8 | | Storage | 0.5 GB | 3 GB | 20 GB | | AI questions per month | 30 | 300 | 1,500 | | Alerts | 0 | 5 | Unlimited | | Scheduled reports | 1 (weekly) | 20 | Unlimited | | Scheduled refresh | No | Hourly or slower | Down to every 15 minutes | | MCP tokens | No | No | Yes | | [Embedded dashboards](/en/docs/dashboards/embed) | No | No | 5 codes, 10,000 views/month | | Deep thinking | No | Yes | Yes | | Si writes and runs SQL/Python ([exploration sandbox](/en/docs/ask/sandbox)) | No | No | Yes (each run counts as 1 question) | Each workspace has its own plan and limits. The Enterprise plan is set by contract: several workspaces, and MCP tokens that can read several of the organization's workspaces. Sample workspaces don't count towards your workspace limit. ## Check your usage **Settings → Plan and usage** (Admin role or above) has three cards: **Usage** (usage against each limit), **Plan features** and **Add-ons**. | Add-on | Price | Plans | | --- | --- | --- | | 500 questions for Si | 99,000 ₫ (about US$4), for the current period | All plans | | 1 extra source | 99,000 ₫ (about US$4) per month | Starter and above | | 10 GB extra | 49,000 ₫ (about US$2) per month | All plans | | 10,000 extra embedded-dashboard views | 99,000 ₫ (about US$4) per month | Small Business and above | Click **Upgrade** to pick a plan or add-on and pay online: QR bank transfer in VND or an international card. The Enterprise plan is billed by contract. DataxLand never charges overages automatically. ## When you hit a limit DataxLand uses soft limits: it only blocks **creating more**, never viewing. - From 80% of a limit, Admins and Owners see a warning. - Out of Si questions: asking Si (in the app, Slack, Telegram, MCP) pauses until the next period. A banner reads "This month's Si questions are used up: asking Si is paused until the next period; dashboards and reports keep running.", with a **See plan and usage** link. - Out of embedded-dashboard views: embedded pages show "paused" until the next period; dashboards in the app keep running. The Owner gets an email at 80% and 100%. - Out of source, alert, report or user slots: what you already have keeps working; upgrade or buy an add-on to create more. - Storage above 110%: scheduled refresh pauses and you can't add sources; dashboards keep showing the data you already have. - Dashboards, running reports and alerts, and [data export](/en/docs/workspace/export-delete) are never blocked. When a plan expires, the workspace returns to the Free plan; your data stays as it is. Over the API, a blocked action returns HTTP 402 with code `quota_exceeded`; see [API](/en/docs/api/overview). ## Related - [Pricing](/en/pricing) - [Members and roles](/en/docs/workspace/members) - [Refund policy](/en/refund) --- # Sync modes and refresh schedule > The three ways to sync data — full, incremental and CDC (change log) — which sources support which, and how to set an automatic refresh schedule. ## Three sync modes | Mode | How it works | Keep in mind | | --- | --- | --- | | **Full** | Re-reads the whole table on every refresh | Simplest; slow on large tables | | **Incremental** | Reads only rows whose cursor column (for example `updated_at`) is newer than last time, merged on the primary key | Does not see rows deleted at the source | | **CDC (log-based)** | Reads the database's change log, including deleted rows | PostgreSQL only; logical replication must be enabled | | Source | Full | Incremental | CDC | | --- | --- | --- | --- | | Excel files | Yes | — | — | | PostgreSQL | Yes | Yes | Yes | | MySQL / MariaDB, SQL Server | Yes | Yes | — | | BigQuery, marketplaces, connectors | Yes | Yes | — | File sources are always re-read in full. Marketplaces (Shopee, TikTok Shop, Lazada) are read incrementally by order update time. ## Change the sync mode 1. Go to **Data sources**, card **Sync method**, and click **Edit sync method**. 2. Choose a mode for each table. For **Incremental**, pick the **Cursor column** (columns marked "(suggested)" are DataxLand's suggestions) and the **Primary key**. 3. Click **Save sync method**. The next refresh does one full load for every table whose settings changed. When a new workspace is created, every table is loaded in full; you can change the sync mode once the workspace exists. For CDC, read the requirements under [PostgreSQL](/en/docs/sources/postgres#cdc). ## Refresh schedule 1. On the **Data refresh schedule** card, choose a **Frequency**: every 15 minutes, every 30 minutes, hourly, daily, weekly or monthly. 2. Choose the **Time** (for daily, weekly and monthly schedules), and the **Day of week** or **Day of month** (1–28). 3. Switch on **Turn on automatic refresh** and click **Save schedule**. The default is daily at 06:00 in the workspace time zone. Every 15 and every 30 minutes are only available when every source syncs incrementally or with CDC. Schedules only run once the workspace is approved. | Plan | Frequencies available | | --- | --- | | Free | No schedule; upload new files by hand (**Thay file**, replace file) | | Starter | Hourly, daily, weekly, monthly | | Small Business and above | Down to every 15 minutes | A schedule your current plan does not include is skipped, with the reason logged. When storage goes above 110% of your quota, refreshes pause; see [Plans and quotas](/en/docs/billing/quotas). ## Related - [Connect your data](/en/docs/connect-data) - [PostgreSQL and CDC](/en/docs/sources/postgres) - [Verified numbers](/en/docs/data-quality) --- # Workspace > A workspace is the unit of data, members and plan in DataxLand — its states from creation to ready, the navigation bar and the roles. A **workspace** brings together the data sources, private warehouse, metrics, dashboards, members and plan of one business, brand or unit. Data in one workspace can never be read from another. ## States | State | Meaning | Next step | | --- | --- | --- | | Creating | Loading sources | Wait | | Data read | Loaded, no proposal yet | **Ask Si to propose** | | Awaiting review | Si has made a proposal | **Review proposal** or **Propose again** | | Approved | Approved, not built yet | **Build** | | Ready | Dashboards published | **Open the dashboard** | | Error | A step failed | **Resume** or **Edit approved mapping** | Only Admins and the Owner see the buttons outside the dashboards. See [Review the proposal and build](/en/docs/review/mapping). ## Navigation bar | Group | Items | | --- | --- | | (top) | Workspace (list of workspaces), Home | | Reports | The pack's dashboard pages and the workspace's own pages | | Ask and explore | Ask Si, Metric handbook, Business model, Knowledge | | Data and connections | Data sources, Reports and alerts, Review proposal, Data health, Settings | Items you have no permission for are hidden. The order and which pages appear in the menu can be changed under **Settings → General → Menu layout and Home**. ## Roles | Role | Can do | | --- | --- | | Owner | Everything: plan and billing, members, deleting the workspace | | Admin | Data sources, reviewing proposals, settings, MCP tokens | | Analyst | Ask Si, explore data, create metrics and draft pages | | Viewer | View dashboards and saved pages only | Each workspace has exactly one Owner. See [Members and roles](/en/docs/workspace/members). ## Industry and department packs When you create a workspace, Si picks the closest **data type** (industry × department, for example retail · sales). The data type decides the standard model, the metrics and the dashboard pages you get out of the box. You can change it during setup in the **Data type** box, with **Change and let Si analyze again**. See the [dashboard templates](/en/dashboards). ## Demo workspace The demo workspace runs on simulated data, carries a **Demo** label and does not count towards your plan's workspace limit. Deleting it is immediate, with no recovery window. ## Related - [Quickstart](/en/docs/quickstart) - [Time zone, currency and formats](/en/docs/workspace/region) - [Plans and quotas](/en/docs/billing/quotas) --- # Metrics and the semantic layer > Every number has one versioned definition; dashboards, Si, reports and MCP read that same definition through the semantic layer, with a Standard, Approved or Unconfirmed confidence level. ## One definition for every number Each metric declares its formula, the dimensions it can be split by (date, channel, product…), its time grain (day, week, month), its unit and its good direction (is up good or bad?). Dashboards, Si, scheduled reports, alerts and [MCP](/en/docs/mcp) all get their numbers from **the same metric engine**: there is no separate SQL hidden in a dashboard or in one of Si's answers. ## The semantic layer The semantic layer describes which tables join to which, which dimensions can split a number and which filters are valid. A question, a dashboard tile and an MCP call are all the same combination: | Part | Example | | --- | --- | | Metric | Net revenue, profit after fees | | Dimension | Channel, product, date | | Filter | Channel = Shopify | | Period | Last month, last 28 days | | Comparison | Versus previous period | DataxLand builds the query from that combination. You can view and edit the workspace's semantic model under **Settings → Data model**, Admin and above. ## Three confidence levels | Level | Where it comes from | When to trust it | | --- | --- | --- | | **Standard** | A metric from the industry × department pack | Shared definition, tested against expected numbers | | **Approved** | Your workspace's own metric (`ws.`) | Checked against data and activated by an Admin | | **Unconfirmed** | An exploratory answer from Si on the approved model | Check it before using it as an official number | Every number is shown with its confidence label. An **Unconfirmed** answer you use often can become a workspace metric, see [Workspace metrics](/en/docs/metrics/workspace-metrics). ## Metric handbook The **Metric handbook** page, in the **Ask and explore** group, has two tabs: - **Metric library**: every metric currently available, searchable with the box "Search metrics (e.g. profit, refunds, ROAS)". Click **Edit description** to change the display name, description, synonyms and notes for your workspace (the formula stays the same). Edited metrics carry an **Edited by workspace** label; **Restore original** puts back the pack version. - **Workspace metrics**: the metrics you define yourself. ## Versions Changing a formula bumps the version. The **Sources** section of every answer lists the metric, its version, the period and the "data as of" date; the [number inspector](/en/docs/ask/inspector) shows the formula, filters, comparison period and the SQL that ran. ## Dates and time zones Timestamps are stored in UTC; business dates follow the workspace time zone (default Asia/Ho_Chi_Minh, changeable per workspace). Weeks start on Monday. See [Time zone, currency and formats](/en/docs/workspace/region). ## Related - [Verified numbers](/en/docs/data-quality) - [Dashboard templates by industry](/en/dashboards) - [The semantic layer on the platform page](/en/platform/semantic-layer) --- # Workspace knowledge > Teach Si about your business with instructions, terms, business events, confirmed answers and documents; Si only uses approved entries. The **Knowledge** page, in the **Ask and explore** group, holds what Si needs to know but the data does not say: "a wholesale order is an order of more than 50 items", "March had a big promotion", "when we say 'profit' we mean profit after marketplace fees". ## Entry types | Tab | Used for | | --- | --- | | Instruction | General guidance for answering | | Term | Your business's own words and what they mean | | Business event | Promotions, price changes, incidents, with an effective period (**Valid from**, **Until**) | | Verified answer | Questions and answers you have marked as correct | | Document | Description files you upload; Si reads them in chunks | **Pinned** entries are always included in Si's instructions. ## Review New entries are **Draft** and sit on the **Awaiting review** tab. Si only uses **Approved** entries. Admins and above click **Approve** or **Reject**; old entries can be archived with **Archive**. Each entry has a **History** of edits. An entry's origin is **Created by a user**, **From a chat** (via the **Save to knowledge** button under an answer) or **Proposed by Si** (when you click **Extract knowledge** on a document or a conversation). ## Documents Upload description documents on the **Document** tab. **Passages Si reads** shows each passage; click **Hide from Si** to make Si skip one. Uploading the document again discards any edits made to its passages. ## Search like Si The **Search like Si** box shows which entries Si would find for a given question, with a similarity score. Use it to check that a new term is picked up. ## Related - [Si](/en/docs/si) - [Ask Si in the app](/en/docs/ask/app) - [Glossary](/en/docs/glossary) --- # Workspace metrics > Define your own workspace metrics (ws.) on the same metric engine, check them against data, activate them and manage versions; review metrics proposed by Si. The industry × department packs are a starting point, not a limit. A workspace can add its own metrics with the id `ws.`, running on the same metric engine as the standard metrics. ## Lifecycle | Status | Meaning | | --- | --- | | Draft | Being written or its calculation just changed; not used in dashboards, Si or MCP yet | | Active | Checked and activated; shows the **Approved** label | | Archived | No longer used, history kept | ## Create a metric 1. Go to **Metric handbook → Workspace metrics**. 2. Click **Create metric**. Declare the calculation from the columns and metrics in the semantic model, the unit and the dimensions allowed. 3. Click **Save draft**. 4. Click **Check**: DataxLand computes the metric over a **Sample period**, shows the **Value** and compares it with a reference metric. The result reads **Number check passed** or **Number check failed**, with the version. 5. An Admin or the Owner clicks **Activate**. Analysts can create, edit and check metrics; activating and archiving need Admin or above. ## Metrics proposed by Si When you ask a question for which Si has to put a formula together itself, Si can propose it as a metric. The proposal appears under **Drafts from Si** with a **Proposed by Si** label. Check it, edit it if needed, then click **Approve**, or **Discard**. ## Versions Changing the calculation or the unit bumps the version and moves the metric back to **Draft**; it has to be checked and activated again. Changing the display name or description does not bump the version. Reports and alerts that use the metric always read the version in use. ## Related - [Metrics and the semantic layer](/en/docs/metrics) - [Ask Si in the app](/en/docs/ask/app) - [Pin to a page](/en/docs/dashboards/pin) --- # Embed a dashboard in your website or app > Put a DataxLand dashboard page into your portal, admin panel or web app with one iframe snippet; lock filters, restrict domains and revoke access at any time. Embedding places **one dashboard page** of your workspace inside another website. Viewers **don't need a DataxLand account**: they see the page's tiles, can change the period and use the filters you open up. There is no Ask Si, no number explainer, no metric handbook and no link back into the app. Embedding is included from the **Small Business** plan up (see [Plans and limits](/en/docs/billing/quotas)): each plan has a number of active embed codes and a number of **views per month**. One view is one load of the embedded page. ## Create an embed code 1. Open the dashboard page (the **Reports** group in the sidebar). If your audience should only see part of the numbers, set the filter first, for example **Channel** = Shop A. 2. Click **Share → Embed dashboard**. This needs the **Admin** role or above. 3. Fill in: - **Label**: helps you recognise the code in the list (e.g. "Shop A partner portal"). - **Allowed domains**: one per line, like `https://portal.example.com`. Use `https://*.example.com` for all subdomains. `http://` only works for `localhost` while testing. Up to 10 domains. - **Expires after**: 7 to 365 days. - **Period when opened**: the period shown when a viewer opens the page; they can change it. - **Lock the current filters**: viewers can't remove these filters. Tiles whose metric can't be filtered by a locked filter are hidden from the embedded page, so unfiltered numbers never leak. - **Viewers can filter by**: dimensions viewers pick values for themselves (e.g. platform). 4. Click **Create embed code**, then **Copy iframe code** or **Copy link**. **The code is shown only this once**; if you lose it, create a new one and revoke the old one. The snippet looks like this: ```html ``` Paste it into an HTML page, CMS or web app served from **one of the declared domains**. Browsers block the frame on any other domain (DataxLand sends a `Content-Security-Policy: frame-ancestors` header built from the code's list). ## What viewers see - The page title, the period picker, the filters you opened up, and the locked filters (with a padlock icon). - The page's tiles, formatted with the workspace's **currency, time zone and number format** ([regional settings](/en/docs/workspace/region)), with the same **Standard** confirmation label as in the app. - Numbers go through the same metric layer as the app: one definition everywhere, and no buyer personal data. ## Manage and revoke The **Embed dashboard** dialog lists the page's codes: domains, expiry, **views this month** and status (**Active**, **Expired**, **Revoked**). Click **Revoke** to stop a code: the embedded page shows "revoked" on its next load. Codes belong to the **workspace**, not to the person who created them: if that member leaves, the code keeps working until an Admin revokes it. Every creation and revocation is recorded in the workspace security log. ## Running out of views, downgrading - At **80%** of the month's views, the Owner gets an email and an in-app notice. - When views run out, embedded pages show "paused" until the next period; dashboards inside the app are unaffected. Buy an extra **10,000 views** or upgrade your plan. - Downgrading to a plan without embedding pauses every embedded page; codes stay in the list and work again after you upgrade (if they haven't expired). ## Security - `frame-ancestors` stops **other** sites from framing the page, but **anyone with the link can open the embedded page** (like a share link). For sensitive numbers: place the iframe only behind your own login, use a short expiry, lock filters, and revoke the code as soon as it leaks. - The embedded page never passes its URL (which contains the code) to other sites (`no-referrer`), is not cached and is not indexed by search engines. - Numbers on the embedded page follow the [row-level access](/en/docs/workspace/data-access) of the person who created the code: if they can only see one branch, the embed only shows that branch. If the creator leaves the workspace, the embed stops showing numbers. - Each code embeds one dashboard page of a pack. Need filtering per signed-in user of your own system? Contact DataxLand. ## Related - [Dashboards and pinning to pages](/en/docs/dashboards/pin) - [Plans and limits](/en/docs/billing/quotas) - [Security and privacy](/en/docs/security-privacy) --- # Workspace pages > Create your own pages, add and edit tiles on the semantic layer without SQL, share a page with the whole workspace, keep or discard draft tiles pinned by Si, and view the history. Besides the pack dashboards, everyone in the workspace can build their own pages: a set of tiles you choose, laid out the way you read them. ## Create a page Pages are created in three ways: - while pinning: **+ Create a new page (private)**, see [Pin to a page](/en/docs/dashboards/pin); - **Copy page** on a dashboard: creates "… (copy)" for you to edit; - by asking Si to pin a result to a new page. ## Edit a page 1. Open the page and click **Edit page**. 2. **Add tile** or edit an existing tile. Each tile is a query on the semantic layer (metric, dimension, filters, period); no SQL is written. 3. Click **Preview**, then **Update tile**. 4. Click **Save page**, or **Cancel**. **History** shows past edits; **Delete page** removes the page. ## Private and shared | Label | Who sees it | | --- | --- | | Private | Only the creator | | Shared | Every workspace member, including the Viewer role | Tick **Share with everyone in the workspace** while editing the page. Creating, editing and sharing pages needs the Analyst role or above. Viewers do not see private pages or draft tiles. ## Si's draft tiles When Si pins something, the page shows "This page has draft tiles pinned by Si; press Save to keep or Discard to remove each one." Each draft tile carries a **Draft** label and two buttons, **Save** and **Discard**. A tile shows **This tile can't show its numbers yet** when its metric is no longer usable, for example a workspace metric that has been archived. ## Menu and home page Admins reorder pages, hide or show them in the menu and choose the home page under **Settings → General → Menu layout and Home**, then **Save layout**. ## Related - [Dashboards and pinning to a page](/en/docs/dashboards/pin) - [Reports and alerts](/en/docs/alerts-reports) - [Metrics and the semantic layer](/en/docs/metrics) --- # Dashboards and pinning to a page > Read a pack dashboard (period, filters, Why?), share it, and pin a result from the number inspector or one of Si's answers to your own page. ## Reading a dashboard The pages in the **Reports** group of the sidebar are the pack's dashboards, built after each build. - **Period**: last 7 days, last 28 days, **last 90 days** (default), this month, last month or custom, then **Apply**. - **Filters**: **Add filter → Filter by**, for example by channel, then **Apply**; **Clear filters** removes them. - **Number tiles**: the **Previous period** line gives the comparison; click **Why?** to open the [number inspector](/en/docs/ask/inspector) on its **Why it changed** tab. The **Details** button on each tile, or a click on a bar or point of a chart, opens the inspector: summary, breakdown, SQL. - **Ask Si**: the button in the top bar opens a panel to ask Si about the page you are viewing, with suggestions such as "Summarise this page". At the top of the page you have **Copy page** (makes a private copy you can edit) and **Share**: **Schedule a report**, **Set an alert**, **Send to Google Sheets** and [**Embed dashboard**](/en/docs/dashboards/embed) (embed the page in your own website, Admin and above). ## Pin to a page A pinned tile **re-runs exactly that query every time the page opens**, with the latest numbers; it is not a screenshot. 1. Open the result you want to pin: - on a dashboard: click **Details** on a tile, **Why?**, or a point on a chart to open the inspector; - in **Ask Si**: adjust **How the question was understood** if needed and click **Run again**; the result card has a pin button. 2. Click **Pin to page**. 3. Set the **Tile title**, pick a **Chart type** and the target page. Private pages are marked "(private)". Choose **+ Create a new page (private)** and fill in **New page name** to create one. 4. Click **Pin**. The confirmation **Pinned to the page …** has an **Open page** button. Si can pin for you too when you ask ("pin this chart to the Channel watch page"). Tiles pinned by Si carry a **Draft** label until you click **Save** on the page. Pinning needs the Analyst role or above. ## Related - [Workspace pages](/en/docs/dashboards/pages) - [Embed a dashboard in your website](/en/docs/dashboards/embed) - [Number inspector](/en/docs/ask/inspector) - [Dashboard templates by industry](/en/dashboards) --- # Review the proposal and build > See which metrics and dashboard pages Si will build, your answers and the assumptions, fix mappings in the proposal review screen (yellow cells), approve, build and follow progress until the dashboard is ready. Nothing is built until the workspace is approved. Approving needs the Admin or Owner role. ## 1. The review and build step The **Approve and build** card sums up what will happen: | Section | Contents | | --- | --- | | How Si reads your data | The domain, what the data is about, what each row represents | | Si will build | The number of metrics and dashboard pages; each page with its main tiles; how each metric is calculated. Without a date column, metrics are current values, not compared across periods | | Metrics not available yet | With a ready-made template: metrics hidden for now and why, for example "Not enough data to compute it." | | Data needed for the unavailable metrics | Fields that the template's hidden metrics need | | Your answers | Your choices in the clarify and review step | | Assumptions | The readings Si uses to build the dashboard, which you accepted in the previous step | | Data load scope | Tables and date range being loaded | Everything Si was unsure about has already been asked in the **Clarify and review** step or recorded as an assumption, so no "unsure" items are left here. If an assumption is wrong, click **Back** and choose again. Open **Menu layout and Home** to see the menu Si proposes. Click **Approve and build**, or **Back** to make changes. ## 2. Fix details in the proposal review screen The **Review proposal** screen, in the **Data and connections** group, lets you edit each part. **Yellow cells are where Si is unsure (score below 80%)**. | Tab | What you edit | | --- | --- | | Business model | What the business sells, through which channels, what each table is | | Mapping | Which source column feeds which standard field (order ID, date, amount, fees…) | | Statuses | Which standard status each source status maps to; **every row needs a standard status before approval** | | Open questions | Questions Si is still waiting on | | Metrics | Metrics on or off; a metric marked "Unsure" can only be turned on when you tick **Turn on … anyway. I understand this number may be wrong.** | Switch between **Latest proposal** and **Approved mapping** to compare. To have Si start over, open **Propose again**, add **Notes for Si (optional)** and run it. The **Questions and approval** panel on the right has **Approve** (approve only) and **Approve and build**. For PostgreSQL and BigQuery, **Advanced: run SQL on the source** lets you run read-only SQL yourself to check things, then **Analyze again**. ## 3. Build The build runs in the background, so you can close the page. Progress shows each step: **Open build warehouse**, **Load data**, **Generate models**, **Transform data**, **Quality checks**, number reconciliation and **Publish**. Each step is Waiting, Running, Done, Blocked or Failed. - **Done**: the workspace is **Ready**; click **Open the dashboard**. - **Blocked**: a blocking check failed or the numbers do not match the source; see [Verified numbers](/en/docs/data-quality). - **Failed**: click **Resume** after fixing the cause, or **Edit approved mapping**. ## Reviewing again later Adding a source, changing the data type or editing a mapping all create a new proposal. Dashboards in use keep running on the approved version until you approve and build the new one. ## Related - [Answer Si's questions](/en/docs/review/questions) - [Workspace states](/en/docs/concepts/workspace) - [Pin to a page](/en/docs/dashboards/pin) --- # Mask personal data > The data and personal-data step — choose which columns to mask, decide whether raw values may be stored, pick the processing region and consent to sending a masked sample to Si. Once DataxLand has read your source, the **Choose data and personal data** step asks which columns hold personal data. An Admin or the Owner completes this step. ## Choose the columns to mask The **Choose columns to mask** screen has two groups: - **Columns that may contain personal data**: names, phone numbers, emails, addresses and so on that DataxLand detected. - **Other columns**: add a mask here if a column holds personal data that DataxLand missed. Columns flagged `pii` in `data_dictionary` show **From the data dictionary, always masked** and cannot be unmasked. Free-text columns (notes, message bodies) are masked by default because they often contain phone numbers or addresses. ## What masking and hashing mean - **Masking**: the value never enters Si's prompt; Si only sees the masked form. - **Hashing**: as soon as the data is loaded, the value is replaced by a hash with a salt unique to your workspace. You can still count unique customers and join tables, but nobody can read the original value back. ## Storing raw values The box **Allow storing the original values of these columns in the workspace's own warehouse for later use** is off by default. Turn it on and the original values are kept in your private warehouse (still masked from Si and never returned through the API, Si or MCP). The change applies from the next read. Only turn it on when you have a legal basis for storing them. ## Processing region and consent 1. Pick the **Data processing region**. 2. Tick **I agree to send up to 1,000 masked sample rows per table to the model above.** so Si can read the sample. 3. Click **Confirm and let Si analyse**. Si starts its analysis, which usually takes 1–3 minutes. Whenever you add or remove a source, you come back to this step for the new data. ## Related - [Answer Si's questions](/en/docs/review/questions) - [Security and privacy](/en/docs/security-privacy) - [Excel files: the data_dictionary sheet](/en/docs/sources/excel) --- # Answer Si's questions > The clarify and review step — Si explains how it understood your data, then asks a few multiple-choice questions about what you want to track, unclear columns and rows with missing data; how to answer, add context and change the data type. Si does not guess where it is unsure: it asks you. The **Clarify and review** step has two parts: **How Si reads your data** and **Si needs you to choose**. ## How Si reads your data Si reads any kind of data: sales, HR, finance, operations, marketing, education, healthcare and more. This section states the domain, what the data is about and a few questions it can answer. The collapsed **Notes about the data** lists anything worth knowing, for example a schema name that does not match its contents or a column that always holds the same value; these notes never block building the dashboard. Data without a date column still gets a dashboard: the metrics are **current values** of the loaded data (for example headcount or attrition rate), not compared across periods. ## Multiple-choice questions Each question has 2–4 options; one is labelled **Si's suggestion** and is preselected. Questions that accept several answers say "You can pick several." If no option fits, pick **Other** and explain; Si keeps your note as context for its next analysis. Examples: - **What do you want to track first?** (attrition rate, payroll cost, satisfaction, workforce mix): the metrics you choose go to the top of the **Focus** page and onto the home page; - **What are monthlyrate, hourlyrate and dailyrate?** (an amount of money, a plain number, ignore): Si picks the unit and calculation from your answer; - **About 29 rows are missing a department and position. Keep or drop them?**: keep them and they are labelled "Unknown"; drop them and they are left out of every metric of that table; - **Si is not sure: … Is this reading correct?**: something Si could not verify; confirm it or write down the correct reading. With a ready-made analytics template (for example multichannel retail), Si also asks about mappings, such as which order statuses mean a cancelled order. Answer, then click **Save and continue**. Your answers and the assumptions are saved with the approved version; the next time Si re-analyses, your earlier answers become the suggested options. ## Uncertain mappings With a ready-made template, the section **Si isn't sure about N mapping items** shows the confidence of each item (for example 62%). **Si's detailed description of the data** is the full write-up. Fine-tune details in the advanced review screen, see [Review the proposal and build](/en/docs/review/mapping). ## Add context The box **Data context for Si** (optional) takes notes (**Save notes**) and description documents (**Upload description document**). Click **Extract knowledge** and Si turns the terms and rules in the document into [Knowledge](/en/docs/metrics/knowledge) entries awaiting approval. After adding context, click **Let Si analyse again**. ## Change the data type When none of the ready-made templates fits, Si builds a custom pack from the columns of your own data. To use a different template, open the **Data type** box, choose **Change data type** and then **Change and let Si analyze again**. ## Related - [Mask personal data](/en/docs/review/pii) - [Review the proposal and build](/en/docs/review/mapping) - [Si](/en/docs/si) --- # BigQuery > Connect BigQuery with a service account key, choose the billing project and dataset, and set a scan limit to keep query costs under control. BigQuery needs the Starter plan or above. DataxLand runs read queries in the project you specify (Google bills the scanned bytes to that project) and copies the results into the workspace's own warehouse. ## 1. Prepare Google Cloud 1. Create a dedicated service account for DataxLand. 2. Grant **BigQuery Job User** on the project that runs the queries and **BigQuery Data Viewer** on the dataset to read (if the data lives in the same project, grant both there). 3. Create a **JSON** key for the service account and download the file. ## 2. Connect 1. **Data sources → Add source**, pick **BigQuery**. 2. **Project that runs queries (billed)**: the project charged for scanned bytes. 3. **Dataset**: `dataset` or `project.dataset` (add `.table` to read a single table). 4. **Scan size limit**: the maximum bytes a single query may scan, 2 GB by default. A query over the limit is stopped before it runs, with a message showing the estimated size. 5. **Service account key**: paste the JSON file's contents, or use **Or choose a JSON file**. 6. Click **Test connection**, pick tables under **Choose the tables to read** (optionally with **Filter by date (optional)**) and add the source. The key is encrypted at rest and never shown again (the source card shows **Password saved**). ## 3. Sync BigQuery supports **Full** and **Incremental**. Sync large tables incrementally on an updated-at column to cut the bytes scanned. See [Sync modes and refresh schedules](/en/docs/concepts/sync-modes). ## Si investigates with SQL Si may run read-only SQL on BigQuery while investigating, within the same scan limit; a query over the limit waits for your confirmation. ## Related - [PostgreSQL](/en/docs/sources/postgres) - [Connect your data](/en/docs/connect-data) - [Plans and quotas](/en/docs/billing/quotas) --- # Connector library > Over 560 connectors for ads, CRM, payments, analytics and spreadsheets — how to search, pick several sources at once, fill in the form, test the connection and choose data streams. Besides DataxLand's own sources (Excel, PostgreSQL, MySQL, SQL Server, BigQuery, REST API and the marketplaces), the library has **over 560 connectors** built on the open-source Airbyte protocol: ads, CRM, payments, analytics, spreadsheets and productivity tools. Connectors run on DataxLand's servers; you do not need to install or know Airbyte. It needs the Starter plan or above. ## Find a connector - **Search connectors**: type the app name, for example Shopify, Google Sheets or ads. - Filter by group (starting with **All**). The **DataxLand connections** group is always at the top. - Support badges: | Badge | Meaning | | --- | --- | | DataxLand | Written and maintained by DataxLand | | Official | A certified connector in the Airbyte ecosystem | | Community | Contributed by the community; quality varies, so test the connection first | Browse the full catalogue at [/en/connectors](/en/connectors). ## Pick and configure 1. Click **Select** on one or more connectors; the bar at the bottom shows **N connectors selected**. Click **Continue**. 2. Each connector gets its own step. Fields marked * are required. The **How to get the connection details** link opens the vendor's documentation. 3. Click **Test connection**. If you see **Couldn't connect**, read the error message; it is usually a wrong key or a missing permission. 4. Under **Choose the data streams to read**, tick the streams you need (**Select all** to take everything). 5. Under **Review before adding**, check and click **Add N sources**. Password fields are encrypted at rest and never shown again. ## After adding DataxLand reads the data, you confirm which columns to mask, and Si updates its mapping proposal for the new source. Connectors support **Full** and **Incremental** sync. See [Sync modes and refresh schedules](/en/docs/concepts/sync-modes). ## Your software is not listed If it has a REST API that returns JSON, use the [custom REST API](/en/docs/sources/rest-api). If not, export to Excel and use [Excel files](/en/docs/sources/excel). ## Related - [Connect your data](/en/docs/connect-data) - [Personal data masking](/en/docs/review/pii) --- # Excel files > Prepare an .xlsx file for DataxLand — one sheet per table, a data_dictionary sheet describing the columns, size limits — then upload it and replace the file when new numbers arrive. ## 1. One sheet per table - Row 1 holds the column names. No blank header cells, no two columns with the same name. - Up to 200,000 rows per sheet and 50 MB per file. Empty sheets are skipped with a warning. - Sheet and column names are normalised to lowercase ASCII joined by underscores (`Order ID` → `order_id`; accents are stripped, so a Vietnamese header such as `Mã đơn` becomes `ma_don`). - Values are loaded as-is, as text; numeric and date types are inferred in a later step. ## 2. The `data_dictionary` sheet This sheet helps Si understand your data faster and more accurately. Without it DataxLand still reads the file, with a warning that column types and meanings are inferred from the data. If you include it, all four required columns must be present. | Column | Required | Contents | | --- | --- | --- | | `table_name` | Yes | Sheet name | | `column_name` | Yes | Column name; `*` is a row describing the whole table | | `data_type` | Yes | Type in the original system, e.g. `VARCHAR(50)`, `DECIMAL(15,0)`, `DATE` | | `description` | Yes | What the column means | | `key` | No | `PK`, `FK` or `PK, FK`; several `PK` columns form a composite key | | `references` | No | The referenced column, e.g. `products.sku` | | `pii` | No | `Y` for personal data (name, phone, email, address) | Columns marked `pii = Y` are always masked; they cannot be unticked in the column-selection step. ## 3. Upload 1. When you create a workspace (or under **Data sources → Add source**), pick the **Excel file** card and click **Upload file**. 2. Choose the file in the **Data file (.xlsx)** field. Only `.xlsx` is accepted. 3. Click **Create workspace and read data**, or add the source. Blocking errors (blank header cell, duplicate column, too many rows) are shown with the sheet name. ## 4. Replace the file when you have new numbers The Free plan has no refresh schedule. When new numbers arrive, open **Data sources**, card **Replace file**, choose **New file (.xlsx)** and click **Replace file and refresh**. Keep the sheet and column names unchanged so the approved mapping still applies. ## Related - [Personal data masking](/en/docs/review/pii) - [Quickstart](/en/docs/quickstart) - [Excel connector page](/en/connectors/excel) --- # Lazada > Connect Lazada with the Connect with Lazada button (OAuth) to read orders, finance transactions, payouts, returns and products, in Vietnam and every country where Lazada operates. Lazada is one of Southeast Asia's leading marketplaces. Connecting it needs the Starter plan or above. Shops in Vietnam, Thailand, Singapore, Malaysia, the Philippines and Indonesia are supported. ## Connect 1. When creating a workspace, enter the **Workspace name** first. For an existing workspace: **Data sources → Add source**. 2. Click **Connect with Lazada** (or tick **Add to the list and connect after the other connectors**). 3. On Lazada's page, sign in with the seller account and grant access. 4. Back in DataxLand: **Source Lazada connected**. By default the **last 90 days** are read; later runs read incrementally. ## Data read | Table | Contents | | --- | --- | | `orders` | Orders | | `order_items` | Order lines | | `finance_transactions` | Finance transactions: fees, commissions, adjustments | | `payouts` | Payouts to your bank account | | `returns` | Returns and refunds | | `products` | Products | ## If the connection fails - **Contact us to enable** instead of the connect button: the Lazada app keys are not set up on this server. In the meantime, use the export from Seller Center with [Excel files](/en/docs/sources/excel). - **Couldn't connect to the marketplace**: try again, and check that you signed in with the right seller account. ## Related - [Shopee](/en/docs/sources/shopee) · [TikTok Shop](/en/docs/sources/tiktok-shop) - [Connect your data](/en/docs/connect-data) --- # SQL Server / Azure SQL > Connect Microsoft SQL Server, Azure SQL Database, Azure SQL Managed Instance or Amazon RDS for SQL Server with a read-only user, and load tables in full or incrementally by rowversion or an update column. SQL Server / Azure SQL needs the Starter plan or above. DataxLand speaks the TDS protocol directly (no ODBC driver to install), streams rows and copies the tables you pick into the workspace's own warehouse; it only runs `SELECT` statements and never writes to your database. The reading session sets `DEADLOCK_PRIORITY LOW` and waits at most 60 seconds for locks, so it never gets in the way of your running applications. It works with SQL Server 2016 and later, Azure SQL Database, Azure SQL Managed Instance and Amazon RDS for SQL Server. ## 1. Prepare a user Create a dedicated login and user for DataxLand with read-only rights: ```sql -- on master (Azure SQL Database: create a "contained user" directly in the database and skip CREATE LOGIN) CREATE LOGIN dataxland WITH PASSWORD = ''; -- on the database to load CREATE USER dataxland FOR LOGIN dataxland; -- Azure SQL: CREATE USER dataxland WITH PASSWORD = ''; ALTER ROLE db_datareader ADD MEMBER dataxland; -- or: GRANT SELECT ON SCHEMA::dbo TO dataxland; GRANT VIEW DEFINITION TO dataxland; -- read primary keys, foreign keys, column descriptions GRANT SHOWPLAN TO dataxland; -- estimate the cost of Si's SQL (optional) ``` Without `SHOWPLAN`, every SQL statement Si wants to run on the source waits for a technical person to confirm it. If the database only accepts certain IP addresses (Azure firewall, security groups), allow DataxLand's server address (ask support for it). ## 2. Connect 1. **Data sources → Add source**, choose **SQL Server / Azure SQL**. 2. Fill in **Host** (e.g. `your-server.database.windows.net`; without `\instance-name` or `,port`), **Port** (1433 by default; for a named instance use the instance's fixed port), **Database name**, **Schema** (`dbo` by default), **User** and **Password**. 3. **SSL**: - **require** (default): encryption required, self-signed certificates accepted (like `TrustServerCertificate=yes`); suits self-installed SQL Server. - **verify-full**: encryption required and the certificate must be issued by a public CA for the right host name. Recommended for Azure SQL. - **disable**: no encryption; only on a trusted network. Servers that require encryption will refuse it. 4. Click **Test connection**, pick tables (optionally **Filter by date (optional)**), then add the source. The password is encrypted at rest and never shown again. ## 3. Sync modes SQL Server supports **Full** and **Incremental**. For incremental, the best cursor column is a **`rowversion`** column: SQL Server bumps it on every insert or update, so no change is missed even when an application forgets to update `updated_at`. DataxLand suggests rowversion columns first, then timestamp columns such as `updated_at`. If a table has none, add one (existing data is not changed): ```sql ALTER TABLE dbo.orders ADD row_version ROWVERSION; ``` The rowversion watermark never moves past transactions still open when the read starts (`MIN_ACTIVE_ROWVERSION()`), so rows that commit late are picked up next time. With timestamp columns, each read goes back 10 minutes for safety. Incremental doesn't see deleted rows; SQL Server Change Tracking / CDC is not supported today. See [Sync modes and refresh schedule](/en/docs/concepts/sync-modes). ## Data types | SQL Server type | In the dictionary | Notes | | --- | --- | --- | | `tinyint`, `smallint`, `int`, `bigint`, `rowversion` | BIGINT | rowversion read as a number | | `decimal`, `numeric`, `money`, `smallmoney`, `float`, `real` | DECIMAL | | | `bit` | BOOLEAN | `true`/`false` | | `date` | DATE | | | `datetime`, `datetime2`, `smalldatetime`, `datetimeoffset` | DATETIME | `datetimeoffset` converted to Vietnam time (UTC+7) | | `char`, `varchar`, `nchar`, `nvarchar`, `text`, `xml`, `uniqueidentifier`, `time` | VARCHAR | | | `geography`, `geometry`, `hierarchyid` | VARCHAR | read as text (WKT) | | `binary`, `varbinary`, `image` | (left empty) | binary data isn't used | ## Si investigates with SQL Si may run read-only SQL on the source while investigating, within limits on the number of statements and their cost (estimated with `SHOWPLAN_XML`, without running the statement); statements over the limit wait for a technical person to confirm them. ## Related - [PostgreSQL](/en/docs/sources/postgres) - [MySQL / MariaDB](/en/docs/sources/mysql) - [Security and privacy](/en/docs/security-privacy) --- # MySQL / MariaDB > Connect MySQL or MariaDB (including Amazon RDS, Aurora, Azure Database for MySQL and Cloud SQL) with a read-only user, pick tables, and load them in full or incrementally by an update column. MySQL / MariaDB needs the Starter plan or above. DataxLand copies the tables you pick into the workspace's own warehouse through a **read-only** session (`SET SESSION TRANSACTION READ ONLY`), streaming rows so large tables never fill memory; DataxLand never writes to your database. It works with MySQL 5.7 and 8.x, MariaDB 10.x and 11.x, and compatible services (Amazon RDS, Aurora MySQL, Azure Database for MySQL, Google Cloud SQL). ## 1. Prepare a user Create a dedicated user for DataxLand that can only read the database you want to load: ```sql CREATE USER 'dataxland'@'%' IDENTIFIED BY ''; GRANT SELECT, SHOW VIEW ON your_database.* TO 'dataxland'@'%'; ``` - `SELECT` is enough to read tables and list columns, primary keys and foreign keys; `SHOW VIEW` lets it read views. - Don't grant `INSERT`, `UPDATE`, `DELETE`, `FILE`, `PROCESS` or `SUPER`: DataxLand doesn't need them. - Replace `'%'` with DataxLand's server address to restrict where the user can sign in from (ask support for it), and open your firewall for that address. ## 2. Connect 1. **Data sources → Add source**, choose **MySQL / MariaDB**. 2. Fill in **Host**, **Port** (3306 by default), **Database name**, **User** and **Password**. 3. **SSL**: - **prefer** (default): encrypts if the server supports it. - **require**: encryption required, self-signed certificates accepted; if the server has no TLS, the connection fails and no data is sent. - **verify-full**: encryption required and the certificate must be issued by a public CA for the right host name (Azure and Cloud SQL use public certificates; Amazon RDS uses its own CA, so choose require). - **disable**: no encryption; only on a trusted network. 4. Click **Test connection**, pick tables (optionally **Filter by date (optional)**), then add the source. The password is encrypted at rest and never shown again. ## 3. Sync modes MySQL / MariaDB supports **Full** and **Incremental**. Incremental needs a cursor column (DataxLand suggests columns such as `updated_at` or `modified_at`) and a primary key to merge rows; each refresh reads rows whose cursor is newer than last time (minus a 10-minute safety margin). The column should have `ON UPDATE CURRENT_TIMESTAMP` so every edit changes its value. Incremental doesn't see deleted rows; binlog-based CDC is not supported for MySQL today. See [Sync modes and refresh schedule](/en/docs/concepts/sync-modes). ## Data types Data lands in the warehouse as is, as text; the data dictionary records each type so the standardisation step reads it correctly: | MySQL type | In the dictionary | Notes | | --- | --- | --- | | `tinyint`, `smallint`, `int`, `bigint` (including `unsigned`), `year` | BIGINT | | | `decimal`, `float`, `double` | DECIMAL | all decimal places kept | | `bit(1)` | BOOLEAN | `true`/`false`; other `bit(n)` read as numbers | | `date` | DATE | the date `0000-00-00` becomes empty | | `datetime`, `timestamp` | DATETIME | `timestamp` is read in Vietnam time (UTC+7) | | `time`, `char`, `varchar`, `text`, `enum`, `set`, `json` | VARCHAR | `time` as `HH:MM:SS` | | `blob`, `binary` | (left empty) | binary data isn't used | ## Si investigates with SQL As with PostgreSQL, Si may run read-only SQL on the source while investigating, within limits on the number of statements and their cost (estimated with `EXPLAIN`); statements over the limit wait for a technical person to confirm them. ## Related - [PostgreSQL](/en/docs/sources/postgres) - [SQL Server / Azure SQL](/en/docs/sources/mssql) - [Security and privacy](/en/docs/security-privacy) --- # PostgreSQL > Connect a PostgreSQL database with a read-only user, pick tables, and sync with full reload, incremental or CDC; CDC requirements on self-managed Postgres, RDS, Cloud SQL, Neon and Supabase. PostgreSQL needs the Starter plan or above. Data is copied into the workspace's own warehouse over a read-only connection; DataxLand never writes to your database. ## 1. Prepare a user Create a dedicated, read-only user for DataxLand: ```sql CREATE ROLE dataxland LOGIN PASSWORD ''; GRANT USAGE ON SCHEMA public TO dataxland; GRANT SELECT ON ALL TABLES IN SCHEMA public TO dataxland; ``` If the database only accepts connections from specific IPs, allow the DataxLand server address (ask support for it). ## 2. Connect 1. **Data sources → Add source**, pick **PostgreSQL**. 2. Fill in **Host**, **Port** (default 5432), **Database name**, **Schema** (default `public`), **User** and **Password**. **SSL**: default, prefer, require or disable; use require when the database is outside your private network. 3. Click **Test connection**. 4. Under **Choose the tables to read**, tick the tables. Optional **Filter by date (optional)**: pick a date column, a from date and a to date to load only that range. 5. Add the source. The password is encrypted at rest and never shown again. Change it later in the **Connection and tables → Edit connection** card; changes apply from the next refresh. ## 3. Sync modes PostgreSQL supports all three: **Full**, **Incremental** (needs a cursor column such as `updated_at` and a primary key) and **CDC** (log-based). See [Sync modes and refresh schedules](/en/docs/concepts/sync-modes). ## CDC CDC reads the change log (WAL) through logical replication, so it sees updated and deleted rows and allows refreshes as often as every 15 minutes. DataxLand creates its own `pgoutput` replication slot for the source; the first sync is a full load. Click **Check CDC requirements** on the source page. Each item shows **Passed** or **Not passed**: | Requirement | How to meet it | | --- | --- | | `wal_level = logical` | Set `wal_level = logical` and restart Postgres. RDS, Aurora: `rds.logical_replication = 1`. Cloud SQL: `cloudsql.logical_decoding = on`. Neon, Supabase: turn on Logical Replication in the project settings | | REPLICATION privilege | `ALTER ROLE dataxland WITH REPLICATION;` (RDS: `GRANT rds_replication TO dataxland;`) | | A free replication slot | Raise `max_replication_slots` or drop unused slots | | Tables have a primary key or REPLICA IDENTITY FULL | Add a primary key, or `ALTER TABLE table_name REPLICA IDENTITY FULL;` | | A publication can be created | The user owns the tables and has CREATE on the database, or an administrator creates it up front: `CREATE PUBLICATION publication_name FOR TABLE table_a, table_b;` | ### Monitor lag Click **View CDC lag** to see how much WAL the slot is holding. When the slot holds more than 1 GB, the page warns **The CDC slot is holding more than 1 GB of WAL.**: refresh more often. A slot that has not synced for 7 days is dropped by DataxLand so it cannot fill your database's disk (you are warned from day 5); the next sync then does a full reload. ## Si investigates with SQL On PostgreSQL, Si may run read-only SQL against the source while investigating, within a limit on the number of queries and their cost. You can run queries yourself too, under **Review proposal → Advanced: run SQL on the source**, with the **Estimate** and **Run on the database** buttons. ## Related - [Connect your data](/en/docs/connect-data) - [BigQuery](/en/docs/sources/bigquery) - [Security and privacy](/en/docs/security-privacy) --- # Custom REST API > Connect any software with a REST API that returns JSON (POS, CRM, inventory, in-house ERP) by declaring the base URL, authentication, endpoints and pagination, then test the call before adding it. Use this connector when your software is not in the [connector library](/en/docs/sources/connector-library) but has a REST API that returns JSON. It needs the Starter plan or above. ## 1. URL and authentication - **API base URL**: must start with `https://`. DataxLand only sends read requests, and only to the host of this URL. - **Authentication**: | Type | You fill in | | --- | --- | | No authentication | — | | API key | The key, the **header or parameter name**, and whether to **send it in** a header or the query string | | Bearer token | The token | | Basic (username, password) | Username, password | | OAuth2 client credentials | Token URL, client ID, client secret, scope | - **Extra headers** (up to 30): fixed headers the API needs. Do not put secrets here; secrets belong in the authentication fields, which are encrypted at rest. ## 2. Endpoints Each endpoint (1–20) becomes one table: | Field | Example | | --- | --- | | Table name | `orders` | | Path | `/v1/orders` | | Parameters | `updated_from` = `{{ start_date }}` | | Path to the record list | `data.items` | | Primary key | `id` | | Pagination | see below | | Maximum pages | 1000 by default | **Pagination**: none, by page number, by offset (limit/offset), by cursor, or by next-page link. Shared fields: **Fetch data from date** (the value of `{{ start_date }}`) and **Timeout per call (seconds)**, 30 by default. ## 3. Test the call Click **Try it**: DataxLand calls the endpoint and shows up to 20 records plus the **Inferred columns**, with personal data already masked. Adjust the list path or pagination until it looks right, then add the source. ## Current limits - Calls use GET, POST or GraphQL; responses must be JSON. - Each refresh reads everything again (filtered from **Fetch data from date**). ## Related - [Connector library](/en/docs/sources/connector-library) - [Connect your data](/en/docs/connect-data) - [Personal data masking](/en/docs/review/pii) --- # Shopee > Connect a Shopee shop with the Connect with Shopee button (OAuth) — no password to paste — to read orders, settlements, returns, products and ads. Shopee is one of Southeast Asia's largest marketplaces, and DataxLand reads it natively. Connecting Shopee needs the Starter plan or above. You grant access on Shopee's own page; DataxLand never sees your shop password. ## Connect 1. When creating a workspace, enter the **Workspace name** first. For an existing workspace: **Data sources → Add source**. 2. Click **Connect with Shopee**. If you are picking several sources at once, tick **Add to the list and connect after the other connectors**; marketplaces are connected last. 3. On Shopee's page, sign in with the shop owner account and grant access. 4. Shopee sends you back to DataxLand: **Source Shopee connected**. If other marketplaces are still queued, click **Connect … next** or **Skip**. By default the **last 90 days** are read; change this with **Fetch data from date**. Later runs read incrementally by order update time. ## Data read | Table | Contents | | --- | --- | | `orders` | Orders, status, timestamps | | `order_items` | Order lines | | `escrow_details` | Settlement: marketplace fees, payment fees, vouchers, payout amount | | `returns` | Returns and refunds | | `products` | Products | | `ads_daily` | Daily Shopee ads spend | Buyers' names, phone numbers and addresses are masked and hashed, as with every other source. ## If the connection fails - The card says **Contact us to enable** instead of showing the connect button: the Shopee app keys are not set up on this server. In the meantime, export your reports from Shopee to Excel and use [Excel files](/en/docs/sources/excel). - You see **Couldn't connect to the marketplace** on return: you cancelled or the authorization session expired; click connect again. ## Related - [TikTok Shop](/en/docs/sources/tiktok-shop) · [Lazada](/en/docs/sources/lazada) - [Shopee connector page](/en/connectors/shopee) - [Sync modes and refresh schedules](/en/docs/concepts/sync-modes) --- # TikTok Shop > Connect TikTok Shop with the Connect with TikTok Shop button (OAuth) to read orders, payment statements, statement transactions, returns and products. TikTok Shop is one of the fastest-growing commerce channels in Southeast Asia, and DataxLand reads it natively. Connecting it needs the Starter plan or above. You grant access on TikTok Shop's own page; DataxLand never sees your password. ## Connect 1. When creating a workspace, enter the **Workspace name** first. For an existing workspace: **Data sources → Add source**. 2. Click **Connect with TikTok Shop** (or tick **Add to the list and connect after the other connectors** when picking several sources). 3. On TikTok Shop's page, sign in with the seller account and grant access. 4. Back in DataxLand: **Source TikTok Shop connected**. By default the **last 90 days** are read (change it with **Fetch data from date**); later runs read incrementally. ## Data read | Table | Contents | | --- | --- | | `orders` | Orders | | `order_items` | Order lines | | `statements` | Payment statements per period | | `statement_transactions` | Statement transactions: fees, commissions, adjustments | | `returns` | Returns and refunds | | `products` | Products | TikTok ads spend is not part of this connector; add an ads connector from the [library](/en/docs/sources/connector-library) if you need it. ## If the connection fails - **Contact us to enable** instead of the connect button: the TikTok Shop app keys are not set up on this server. In the meantime, use the export from Seller Center with [Excel files](/en/docs/sources/excel). - **Couldn't connect to the marketplace**: you cancelled or the authorization session expired; try again. ## Related - [Shopee](/en/docs/sources/shopee) · [Lazada](/en/docs/sources/lazada) - [Connect your data](/en/docs/connect-data) --- # Air-gapped mode > Run DataxLand on a network with no Internet access - the allow-list of hosts, the required NetworkPolicy, an in-house AI model, internal SMTP, features that turn off, data sources that still work and how to copy images into an internal registry. Air-gapped mode is for installations that must not reach the Internet. When it is on, DataxLand only calls the hosts you list, turns off the features that need an external host on its own, and tells you why. DataxLand sends no telemetry back to DataxLand, air-gapped or not. The license is checked offline. ## 1. Turn on the mode and declare the allowed hosts ```yaml airgapped: enabled: true egressAllow: - llm.corp.example # exact name - smtp.corp.example - "*.db.corp.example" # every subdomain of db.corp.example - 10.20.0.0/16 # address range (CIDR) ``` Each entry takes one of three forms: | Form | Example | Matches | | --- | --- | --- | | Exact name | `llm.corp.example` | That name only | | `*.suffix` | `*.db.corp.example` | `pg.db.corp.example`, `a.b.db.corp.example`; not `db.corp.example` itself | | CIDR or IP | `10.20.0.0/16`, `10.20.1.5` | Hosts that resolve to an address in the range | - Cloud metadata addresses and link-local (`169.254.0.0/16`) are **always blocked**, even when they are on the list. - The AI model and SMTP are checked by **name** from the configuration at startup. List their host names (or IPs if they are configured by IP), not just a CIDR range. - Even without air-gapped mode this list is useful: by default DataxLand refuses connections to internal addresses (SSRF protection), so a source database on your network must be in `egressAllow` before you can connect to it. ## 2. Block at the network level (required) The in-app check is the second layer. Connector subprocesses don't carry the application's policy, so the primary layer has to be the chart's NetworkPolicy and your firewall: ```yaml networkPolicy: enabled: true egress: restrict: true dnsNamespace: kube-system allowCIDRs: [10.0.0.0/16, 10.20.0.0/16] # Postgres, object storage, AI model, SMTP, source databases allowPorts: [5432, 443, 587, 1433, 3306, 8000] ``` Helm warns you when `airgapped.enabled` is on but `networkPolicy.egress.restrict` is off. Requires a CNI that supports NetworkPolicy. ## 3. In-house AI model The default model catalog in the image calls an external provider's API. In air-gapped mode every route must point to a model whose host is in `egressAllow`; otherwise the application reports a configuration error at startup, naming the route and the offending host. Set your own catalog with `llm.modelsYaml`, using `openai_compat` models (vLLM, Ollama, LM Studio, TGI): ```yaml llm: modelsYaml: | models: internal-qwen: provider: openai_compat base_url: http://llm.corp.example:8000/v1 # vLLM model: Qwen/Qwen3-32B api_key_env: INTERNAL_LLM_API_KEY # key in the dataxland-env Secret; null if not needed capabilities: [structured_output, tool_use] region: local internal-ollama: provider: openai_compat base_url: http://ollama.corp.example:11434/v1 # Ollama model: qwen3:32b api_key_env: null capabilities: [structured_output, tool_use] region: local routes: {copilot: internal-qwen, agent: internal-qwen} ``` - The `copilot` route (Si analysing your data context) needs a model with `structured_output`; the `agent` route (Si answering questions) needs `tool_use`. - Only declare capabilities the model really handles well. The quality of Si's answers depends on the model you choose; test it on your own data before rolling it out. - `llm.copilotModel` and `llm.agentModel` pick a model by its catalog name without editing `routes`. ## 4. Email through internal SMTP ```yaml deployment: extraEnv: DX_SMTP_HOST: smtp.corp.example DX_SMTP_PORT: "587" DX_SMTP_USER: dataxland DX_SMTP_FROM: dataxland@corp.example ``` Put the password in the `DX_SMTP_PASSWORD` key of the Secret. In air-gapped mode, email is turned off if the SMTP host is not in `egressAllow`. ## 5. Features that turn off In air-gapped mode the following features turn off automatically when the hosts they need are not in `egressAllow`: | Feature | Hosts needed | | --- | --- | | Google sign-in | `accounts.google.com`, `oauth2.googleapis.com` | | Turnstile CAPTCHA | `challenges.cloudflare.com` | | Shopee, TikTok Shop, Lazada marketplace connections | The marketplace's API and login hosts | | Telegram channel | `api.telegram.org` | | Slack channel | `slack.com`, `hooks.slack.com` | | Microsoft Teams channel | `login.microsoftonline.com`, `login.botframework.com`, `smba.trafficmanager.net` | | Google Sheets | `sheets.googleapis.com`, `oauth2.googleapis.com` | | Email | Your SMTP server | | Trace export (OTLP) | The trace collector | Every OAuth connection (marketplaces and the connector library) is **off by default** in air-gapped mode. To turn them on, list them in `DX_OAUTH_PROVIDERS` under `deployment.extraEnv`; a marketplace still stays off if its hosts are not in `egressAllow`. See the actual list for your installation in **Admin → Operations**, section **Deployment and licence**: the outbound hosts allowed and each disabled feature with its reason. Or run: ```bash kubectl -n dataxland exec deploy/dataxland-worker -- python -m pipelines.cli license-status ``` ## 6. Data sources By default, air-gapped mode keeps the sources that ship in the image and connect to hosts you enter: **Excel**, **PostgreSQL**, **MySQL** and **SQL Server**. The database host must be in `egressAllow` and allowed by the NetworkPolicy. BigQuery, the connector library and the Singer, dlt and Airbyte runtimes are only enabled when you set `DX_SOURCE_CONNECTORS` in `deployment.extraEnv`, and each connection is still blocked if its host is not allowed. Airbyte connectors that install from PyPI at run time, or manifest connectors that are not yet cached, cannot run air-gapped. ## 7. Copy images into an internal registry The following are **already inside the `api` image** and never downloaded at run time: the embedding model, the DuckDB extensions, and the Singer, dlt and Airbyte connector runtimes. You only need to copy the images. On a machine with Internet access and [skopeo](https://github.com/containers/skopeo), from the DataxLand source bundle shipped with the release: ```bash # List the images python -m tools.mirror_images list --tag --owner # Option 1: an internal registry reachable from this machine python -m tools.mirror_images mirror --tag --owner --to registry.corp.example/dataxland # Option 2: package them to carry into the closed network python -m tools.mirror_images bundle --tag --owner --out ./dx-bundle ``` - The list covers the `api` image (shared by `worker`, `mcp` and the Jobs), `web`, `site`, plus the auxiliary images in the chart (trial Postgres and MinIO, s3proxy). `--with-build` adds the base images if you want to build images inside the closed network. - Images are copied for both amd64 and arm64. `--dry-run` only prints the `skopeo` commands. - `bundle` writes one `oci-archive` file per image, with `images.txt` (file, source image, target name) and `SHA256SUMS`. Inside the closed network, verify `SHA256SUMS`, then load each file: ```bash skopeo copy oci-archive:.tar docker://registry.corp.example/dataxland/: ``` Then point the chart at the internal registry: ```yaml image: registry: registry.corp.example repositoryPrefix: dataxland ``` If you use s3proxy or the trial Postgres and MinIO, also set `s3proxy.image`, `postgres.bundled.image` and `minio.image` to the target names in `images.txt`. ## Related - [Install with Helm](/en/docs/self-host/helm) - [Requirements and sizing](/en/docs/self-host/requirements) - [Offline license](/en/docs/self-host/license) --- # Install with Helm > Install DataxLand on Kubernetes with the Helm chart, including the secrets Secret, the license Secret, minimal production values, post-install checks, a trial setup with in-cluster Postgres and MinIO, External Secrets, NetworkPolicy and ServiceMonitor. This page uses the release name `dataxland`, the namespace `dataxland` and the domain `dataxland.corp.example`. Replace them with your own values. Before you start you need: infrastructure as described in [Requirements and sizing](/en/docs/self-host/requirements), Helm 3, `kubectl` pointed at the cluster, and from DataxLand: the chart, the image repository name, image pull access (or the [offline image bundle](/en/docs/self-host/airgapped#7-copy-images-into-an-internal-registry)) and the license file `license.json`. ## 1. Namespace ```bash kubectl create namespace dataxland ``` Each namespace holds **one** installation: the `api` Service is always named `api` (the `web` image calls `http://api:8000` out of the box). If the image registry requires a login, create an image pull Secret and declare it under `imagePullSecrets`: ```bash kubectl -n dataxland create secret docker-registry dataxland-pull \ --docker-server=ghcr.io --docker-username= --docker-password= ``` ## 2. Secrets Secret The chart contains no secret values. Create one Secret where each key matches an environment variable: | Key | Required | Contents | | --- | --- | --- | | `DX_POSTGRES_URL` | yes | Connection string of the `dx` database, for example `postgresql://dx:@pg.corp.example:5432/dx?sslmode=require` | | `DX_DUCKLAKE_CATALOG_PASSWORD` | yes | Password of the Postgres user (used for the `dx_lake` database) | | `DX_SESSION_SECRET` | yes | Random string that signs login sessions | | `DX_SECRET_KEY` | yes | Random string that encrypts stored secrets (source passwords, tokens) | | `DX_DELEGATION_SIGNING_KEY` | yes | Random string that signs short-lived delegation tokens between services | | `DX_BACKUP_ENCRYPTION_KEY` | yes | 32 bytes, URL-safe base64, encrypts backups | | `DX_DUCKLAKE_S3_KEY_ID`, `DX_DUCKLAKE_S3_SECRET` | yes | Object storage keys | | `DX_SMTP_PASSWORD` | no | SMTP password | | `DX_BACKUP_S3_KEY_ID`, `DX_BACKUP_S3_SECRET` | no | Separate keys for the backup bucket, if they differ from the warehouse keys | | `DX_METRICS_TOKEN` | no | Requires a token to read `/metrics` | | Model API key | depends on the model | Variable name from the model's `api_key_env`. The default catalog uses `DEEPSEEK_API_KEY` | ```bash kubectl -n dataxland create secret generic dataxland-env \ --from-literal=DX_POSTGRES_URL='postgresql://dx:@pg.corp.example:5432/dx?sslmode=require' \ --from-literal=DX_DUCKLAKE_CATALOG_PASSWORD='' \ --from-literal=DX_SESSION_SECRET="$(openssl rand -hex 32)" \ --from-literal=DX_SECRET_KEY="$(openssl rand -hex 32)" \ --from-literal=DX_DELEGATION_SIGNING_KEY="$(openssl rand -hex 32)" \ --from-literal=DX_BACKUP_ENCRYPTION_KEY="$(openssl rand -base64 32 | tr '+/' '-_')" \ --from-literal=DX_DUCKLAKE_S3_KEY_ID='' \ --from-literal=DX_DUCKLAKE_S3_SECRET='' ``` If the Postgres password contains special characters, URL-encode it in `DX_POSTGRES_URL`. **Store `DX_SECRET_KEY` and `DX_BACKUP_ENCRYPTION_KEY` in two places right away** (your company secret store and an offline copy). Lose `DX_SECRET_KEY` and every data source has to be reconnected; lose `DX_BACKUP_ENCRYPTION_KEY` and no backup can be decrypted. ## 3. License Secret ```bash kubectl -n dataxland create secret generic dataxland-license --from-file=license.json=./license.json ``` Without a license the installation still runs, but in read-only mode. See [Offline license](/en/docs/self-host/license). ## 4. Production values A minimal `values-prod.yaml` (AWS example): ```yaml image: repositoryPrefix: imagePullSecrets: - name: dataxland-pull deployment: publicUrl: https://dataxland.corp.example superAdmins: [admin@corp.example] extraEnv: DX_SMTP_HOST: smtp.corp.example DX_SMTP_PORT: "587" DX_SMTP_USER: dataxland DX_SMTP_FROM: dataxland@corp.example license: existingSecret: dataxland-license secrets: existingSecret: dataxland-env postgres: external: host: pg.corp.example database: dx catalogDatabase: dx_lake user: dx objectStorage: endpoint: s3.ap-southeast-1.amazonaws.com region: ap-southeast-1 urlStyle: vhost lakeBucket: dx-lake tenantKeys: "off" backup: bucket: dx-backups persistence: storageClass: efs-rwx size: 100Gi ingress: className: nginx host: dataxland.corp.example annotations: cert-manager.io/cluster-issuer: letsencrypt ``` Keys you will often change: | Key | Meaning | | --- | --- | | `deployment.publicUrl` | The URL users open; required | | `deployment.superAdmins` | Emails of installation-wide admins | | `deployment.signupMode` | `invite` (default), `approval` or `open` | | `deployment.timezone` | Time zone for business dates and backup times, default `Asia/Ho_Chi_Minh` | | `deployment.extraEnv` | Extra environment variables for `api`, `worker`, `mcp` (SMTP, notification channels) | | `image.registry`, `image.repositoryPrefix`, `image.tag` | Image registry; an empty `image.tag` uses the chart version | | `image.digests` | Pin images by digest, for example `{api: sha256:..., web: sha256:...}` | | `objectStorage.lakePrefix` | Prefix inside the warehouse bucket, when the bucket is shared | | `ingress.tls.secretName` | Secret with the certificate; empty means `dataxland-tls` (created by cert-manager) | | `ingress.mcp.enabled`, `ingress.mcp.host` | Expose the MCP server, for example `mcp.dataxland.corp.example` | | `ingress.api.enabled`, `ingress.api.host` | Expose the api's `/v1` directly, only when you need OAuth callbacks or webhooks | | `api.autoscaling.enabled`, `web.autoscaling.enabled` | Enable the HPA | | `mcp.enabled` | Turn off the MCP server if you don't use it | Object storage on GCP, Azure or on-prem: see the table in [Requirements and sizing](/en/docs/self-host/requirements#object-storage-on-each-cloud). ## 5. Install ```bash helm install dataxland -n dataxland -f values-prod.yaml kubectl -n dataxland get pods -w ``` `` is the directory or `.tgz` file of the chart DataxLand ships with the release. On the first install the components create the Postgres schema themselves; on later upgrades the `migrate` Job does it before the new version rolls out. After installing, Helm prints notes, with warnings if the license is missing, if in-cluster Postgres or MinIO is in use, or if the chart generated the Secret itself. ## 6. Check and sign in ```bash kubectl -n dataxland port-forward svc/api 8000:8000 curl -s http://localhost:8000/readyz ``` `/readyz` checks Postgres, the catalog and object storage. Once it succeeds: 1. Open `https://dataxland.corp.example`. 2. **Sign up** with an email listed in `deployment.superAdmins`. This email needs no invitation code and must turn on two-factor authentication. 3. Go to **Admin → Operations**, section **Deployment and licence**: check the license status, usage and air-gapped mode. 4. Create the first workspace, then invite users. License status from the command line: ```bash kubectl -n dataxland exec deploy/dataxland-worker -- python -m pipelines.cli license-status ``` ## Trial with in-cluster Postgres and MinIO To try DataxLand on a small cluster, the chart can run Postgres and MinIO inside the cluster. These two components are **for trials only**: a single replica, no backups, no HA. ```yaml # values-trial.yaml deployment: publicUrl: http://localhost:3000 superAdmins: [admin@corp.example] license: existingSecret: dataxland-license postgres: bundled: enabled: true minio: bundled: true objectStorage: tenantKeys: minio persistence: accessMode: ReadWriteOnce size: 10Gi api: replicas: 1 web: replicas: 1 ingress: enabled: false ``` ```bash helm install dataxland -n dataxland -f values-trial.yaml kubectl -n dataxland port-forward svc/dataxland-web 3000:3000 ``` If you don't set `secrets.existingSecret`, the chart creates the `dataxland-env` Secret itself with random keys and keeps it across upgrades. A trial still needs a license file; without one the installation is read-only. ## Secrets from External Secrets Operator If your secrets live in a secret store (AWS Secrets Manager, Google Secret Manager, Azure Key Vault, Vault) and the cluster runs External Secrets Operator, the chart creates an `ExternalSecret` instead of a hand-made Secret. The target is still the `dataxland-env` Secret. ```yaml secrets: existingSecret: "" externalSecret: enabled: true secretStoreRef: {name: cloud-secrets, kind: ClusterSecretStore} refreshInterval: 1h data: DX_SECRET_KEY: dataxland/prod/secret-key DX_POSTGRES_URL: {key: dataxland-app, property: DX_POSTGRES_URL} ``` Each key in `data` is a variable name; the value is the `remoteKey` in the store, or a full `remoteRef` (`key`, `property`) when several variables live in one JSON secret. List every required key from section 2. ## NetworkPolicy Requires a CNI that supports NetworkPolicy. Enable it with: ```yaml networkPolicy: enabled: true ingressControllerNamespace: ingress-nginx ingressControllerLabels: {app.kubernetes.io/name: ingress-nginx} monitoringNamespace: monitoring ``` The chart denies all inbound traffic, then allows only: the ingress controller into `web` and `mcp` (and `api` if `ingress.api` is on), the installation's pods calling each other, and Prometheus in `monitoringNamespace` reading metrics ports 9464 to 9466. Restricting outbound traffic (required in air-gapped mode): ```yaml networkPolicy: enabled: true egress: restrict: true dnsNamespace: kube-system allowCIDRs: [10.0.0.0/16] allowPorts: [5432, 443, 587] ``` With `restrict: true`, pods may only call DNS, pods of the same installation and the ranges in `allowCIDRs` (Postgres, object storage, AI model, SMTP, source databases). An empty `allowPorts` means every port to those ranges. ## ServiceMonitor With Prometheus Operator: ```yaml serviceMonitor: enabled: true interval: 30s labels: {release: prometheus} ``` The chart scrapes `/metrics` from `api` (port 9464), `worker` (9465) and `mcp` (9466). If you set `DX_METRICS_TOKEN`, the chart's ServiceMonitor does not send the token for you; add authentication to your Prometheus configuration. A set of Prometheus alert rules ships with each release; also load an alert for a license nearing expiry (see [Offline license](/en/docs/self-host/license#monitoring-expiry)). ## Related - [Air-gapped mode](/en/docs/self-host/airgapped) - [Upgrades and backups](/en/docs/self-host/upgrade-backup) - [Offline license](/en/docs/self-host/license) --- # Self-hosting (Enterprise plan) > Run DataxLand in your own Kubernetes infrastructure with a Helm chart, an offline license and an air-gapped mode; when to choose it, what it includes, how it differs from the cloud and its known limits. On the Enterprise plan you can run DataxLand **in your own infrastructure**: data, warehouse and backups live in your cloud account or data centre, the AI model can be one you host yourself, and the installation can run without any outbound Internet access. ## When to self-host - Internal policy or regulation requires that data never leaves your company network. - You need an in-house AI model instead of an external model provider. - Your source databases are only reachable from the internal network and are never exposed outside it. - You have an infrastructure team that runs Kubernetes, Postgres and object storage. Without those constraints, [DataxLand Cloud](/en/pricing) means far less to operate: backups, upgrades and monitoring are handled by DataxLand. ## The model: one installation per customer - One installation serves **one organisation**. It can hold many workspaces and many users, within the limits of your license. - Self-hosted DataxLand runs **the same code and the same images** as DataxLand Cloud. Only the configuration and the license file differ, so features and fixes arrive at the same time. - It installs with a **Helm chart** on any Kubernetes (1.27 or later). **Reference Terraform modules** for AWS, GCP and Azure are included as well. ## Components | Component | Role | Default replicas | | --- | --- | --- | | `web` | User interface | 2 | | `api` | API, dashboards, asking Si | 2 | | `mcp` | MCP server for external agents (can be disabled) | 1 | | `worker` | Ingest and builds, refresh schedules, backups, warehouse maintenance | always 1 | | `migrate` Job | Upgrades the Postgres schema before every upgrade | runs once | | Backup CronJob | Optional, when you want Kubernetes to own the backup schedule | off | Outside the cluster, you provide: - **Managed Postgres 16**: application metadata and the data warehouse catalog. - **S3-compatible object storage**: the data warehouse (Parquet) and backups. - **A shared volume** (PersistentVolumeClaim): uploaded files, workspace configuration, encrypted secrets and the build working directory. Details in [Requirements and sizing](/en/docs/self-host/requirements). ## How it differs from the cloud | | DataxLand Cloud | Self-hosted | | --- | --- | --- | | Infrastructure, backups, upgrades | Run by DataxLand | Your infrastructure team | | Sign-up | Through the sign-up page | Invitation only by default; installation-wide admins are declared by email | | Plan | As subscribed | Enterprise plan, every feature | | Licensing | Billed per plan | [Offline license file](/en/docs/self-host/license), never calls home to DataxLand | | AI model | Models chosen by DataxLand | The default catalog (calls the model provider's API), or your own in-house model | | Outbound Internet | Yes | Your choice; an [air-gapped mode](/en/docs/self-host/airgapped) is available | | Data sent to DataxLand | Not applicable | Nothing is sent to DataxLand | ## Known limits Read these carefully before you plan: - **The shared volume must be ReadWriteMany when you run several nodes.** `api`, `mcp` and `worker` read and write the same directory. In the cloud that means EFS (AWS), Filestore (GCP) or Azure Files (Azure); on-prem, NFS or CephFS. ReadWriteOnce is only enough when the whole installation runs on a single node. NFS performance on the build directory is the biggest operational dependency. - **`worker` runs as a single replica.** The chart pins one replica and updates it with the Recreate strategy: during an upgrade, background work (builds, refresh schedules, backups) pauses for a few minutes. Dashboards and asking Si keep working. - **One object storage key for the whole bucket in the cloud.** On S3, GCS or s3proxy every workspace shares one key; data is separated by path prefix. Per-workspace keys are only available with MinIO. - **Azure Blob goes through s3proxy and has not been tested on a real account.** If you need certainty, run your own MinIO on Azure Disk. - **Terraform is a reference template.** It passes `terraform fmt` and `terraform validate` but has not been applied to a real cloud account. See [Reference Terraform](/en/docs/self-host/terraform). - **Only one installation per namespace**, because the `api` Service has the fixed name `api`. ## Steps 1. Prepare the infrastructure following [Requirements and sizing](/en/docs/self-host/requirements), or build it with the [reference Terraform](/en/docs/self-host/terraform). 2. Contact DataxLand to get your license file and image pull access. 3. [Install with Helm](/en/docs/self-host/helm). 4. If the network has no Internet access: [Air-gapped mode](/en/docs/self-host/airgapped). 5. Schedule backups and rehearse a restore: [Upgrades and backups](/en/docs/self-host/upgrade-backup). ## Related - [Architecture](/en/docs/architecture) - [Security and privacy](/en/docs/security-privacy) - [Enterprise plan](/en/enterprise) --- # Offline license > The license file of a self-hosted installation - what it contains, how to mount it as a Secret, the states and what they mean, the grace period, a read-only mode that never locks your data, renewal, the license-status command and the dx_license_days_left metric. Self-hosted DataxLand uses an **offline license**: a `license.json` file DataxLand issues under your contract. The installation verifies the file's signature with a public key built into the image, **never calls home to DataxLand** and works on a closed network. ## What the file contains The JSON file holds the format (`dataxland-license/1`), the signing key ID, a payload and a digital signature. The payload records: | Field | Meaning | | --- | --- | | `license_id` | License ID | | `customer` | Customer name | | `edition`, `plan` | Edition and plan (Enterprise) | | `limits.workspaces` | Maximum number of workspaces; `null` means unlimited | | `limits.seats` | Maximum number of users; `null` means unlimited | | `features` | Features under the contract, shown on the admin page | | `issued_at`, `not_before`, `expires_at` | Issue date, start of validity, expiry date | | `grace_days` | Grace period in days after expiry, default 30 | | `deployment` | `selfhost` | Editing the payload breaks the signature and makes the license invalid. To change limits or the term, contact DataxLand for a new file. ## Mount the license ```bash kubectl -n dataxland create secret generic dataxland-license --from-file=license.json=./license.json ``` ```yaml license: existingSecret: dataxland-license key: license.json # name of the key in the Secret that holds the file ``` The chart mounts the file read-only at `/etc/dataxland/license/license.json` in `api`, `worker` and `mcp`. If you install without a license, Helm prints a warning with the commands to create the Secret and upgrade. ## States The installation checks the license at startup, then again **every hour** and **whenever the file changes**. | State | When | Installation | | --- | --- | --- | | `valid` | Within the term | Fully working, workspace and user limits enforced | | `grace` | Expired, still within the grace period | Same as `valid`; the admin page shows a warning | | `expired` | Past the grace period too | Read-only | | `not_yet_valid` | Before `not_before` | Read-only | | `invalid` | Wrong format, bad signature, unknown signing key, not issued for self-hosting | Read-only | | `missing` | No file mounted | Read-only | ### Read-only mode Read-only mode **never locks your data**: - Still working: dashboards, asking Si, MCP, data export, sign-in. - Blocked: creating workspaces, inviting users, running builds or refreshing data. The API returns a 402 error with code `license_inactive`. Data stays at the last build until a valid license is in place. ### Limits - **Workspaces**: counts the active workspaces across the whole installation, including sample workspaces. - **Users**: counts the accounts that are not locked across the whole installation. At a limit you cannot create more workspaces or invite more people (402 error with code `license_limit`); everything that already exists keeps working. Locking accounts that are no longer used frees up seats. ## Check the status In the app: **Admin → Operations**, section **Deployment and licence** shows the customer, license ID, expiry date, days left (including grace), usage against limits and the feature list. From the command line: ```bash kubectl -n dataxland exec deploy/dataxland-worker -- python -m pipelines.cli license-status ``` The command prints JSON with the license state, usage and air-gapped mode, and exits with code 1 when the license is no longer in force, so you can use it in health-check scripts. ## Monitoring expiry `api` exports the Prometheus metric `dx_license_days_left`: the number of days until the installation switches to read-only (including grace), with a `state` label for the current state. Example alert rule: ```yaml - alert: DataxLandLicenseExpiring expr: dx_license_days_left < 45 for: 1h annotations: summary: DataxLand license has under 45 days left; contact DataxLand to renew ``` ## Renewal 1. Contact DataxLand to get a new license file. 2. Replace the Secret's contents: ```bash kubectl -n dataxland create secret generic dataxland-license \ --from-file=license.json=./license.json --dry-run=client -o yaml | kubectl apply -f - ``` 3. Kubernetes updates the mounted file in the pods within a few minutes; the installation notices the change and reloads it, **no restart needed**. Confirm with `license-status` or the admin page. ## Related - [Install with Helm](/en/docs/self-host/helm) - [Air-gapped mode](/en/docs/self-host/airgapped) - [Enterprise plan](/en/enterprise) --- # Requirements and sizing > The infrastructure you need before self-hosting DataxLand (Kubernetes, Postgres 16, S3-compatible object storage, a shared volume, ingress and TLS), the default resources of each component and how to pick object storage on each cloud. ## Infrastructure you need | Item | Requirement | | --- | --- | | Kubernetes | 1.27 or later, amd64 or arm64 nodes (images are multi-arch) | | Postgres | Version 16, a managed service (RDS, Cloud SQL, Azure Database for PostgreSQL) or your own Postgres cluster, with backups | | Databases | Two databases with the same user: `dx` (metadata) and `dx_lake` (warehouse catalog). The application creates `dx_lake` itself if the user has `CREATEDB` | | Object storage | S3-compatible: two buckets, one for the warehouse (default `dx-lake`) and one for backups (default `dx-backups`) | | Shared volume | A StorageClass that can provision `ReadWriteMany` PVCs (EFS, Filestore, Azure Files, NFS, CephFS). Single node: `ReadWriteOnce` is enough | | Ingress | An ingress controller in the cluster and a domain for `web`, for example `dataxland.corp.example` | | TLS | A certificate in a Secret, or cert-manager issuing one automatically | | Email | An SMTP server for invitations, password resets and reports | | AI model | An API key from a model provider, or an in-house OpenAI-compatible model (vLLM, Ollama, LM Studio, TGI) | Optional: External Secrets Operator (reads secrets from your secret store), Prometheus Operator (collects metrics), a CNI that supports NetworkPolicy (Calico, Cilium, Azure NPM, GKE Dataplane V2, AWS VPC CNI with policy enabled). Pods run as a non-root user (uid 10001) with a read-only root filesystem, all capabilities dropped and `seccompProfile: RuntimeDefault`. These settings match the Pod Security "restricted" standard; we have not yet tested on a cluster that enforces it. ## Default resources From the chart's `values.yaml`. "Request" is what Kubernetes reserves; "limit" is the memory ceiling of each pod. | Component | Replicas | CPU request | Memory request | Memory limit | | --- | --- | --- | --- | --- | | `api` | 2 | 0.5 | 1 Gi | 3 Gi | | `web` | 2 | 0.1 | 256 Mi | 768 Mi | | `mcp` | 1 | 0.25 | 512 Mi | 2 Gi | | `worker` | 1 | 1 | 2 Gi | 7 Gi | | **Total** | | **2.45** | **5 Gi** | **16.5 Gi** | Tune them with `api.resources`, `web.resources`, `mcp.resources` and `worker.resources`. Most of the memory of `api` and `mcp` goes to read-only warehouses: `api.readers` (default `max: 8`, `memory: 256MB`) and `mcp.readers` (`max: 4`, `memory: 256MB`); the product of the two numbers is the read-warehouse memory ceiling per pod. `worker.threads` (default 4) is the number of threads used for builds. ## Sizing guide The numbers below are **starting estimates**, not measurements of your workload. Watch memory and build times for the first few weeks, then adjust. | | Small | Medium | Large | | --- | --- | --- | --- | | Workspaces | up to 10 | 10 to 50 | over 50 | | Kubernetes nodes | 3 × 4 vCPU, 16 GB | 3 × 8 vCPU, 32 GB | 4 or more × 8 vCPU, 32 GB | | `worker` memory limit | 7 Gi (default) | 12 Gi | 16 Gi or more | | `api` | 2 replicas (default) | enable `api.autoscaling` | enable `api.autoscaling`, raise `maxReplicas` | | Postgres | 2 vCPU, 4 GB | 4 vCPU, 16 GB | 8 vCPU, 32 GB | | Shared volume | 100 Gi (default) | 250 Gi | 500 Gi or more | Object storage capacity depends on how much source data you have; compressed Parquet is usually much smaller than the original. The backup bucket needs room for the retained copies (by default 7 daily, 4 weekly, 6 monthly). `worker` always runs as one replica, so as data grows you raise its memory and `worker.threads`, not its replica count. ## Object storage on each cloud DataxLand speaks the S3 protocol. How to connect each option, set under `objectStorage` in your values: | Storage | `objectStorage.endpoint` | `urlStyle` | Credentials | Notes | | --- | --- | --- | --- | --- | | AWS S3 | `s3..amazonaws.com` | `vhost` | Static access key of an IAM user | IRSA and Pod Identity are not supported | | Google Cloud Storage | `storage.googleapis.com` | `path` | HMAC key of a service account | Through the S3-compatible API; paths stay `s3://`, not `gs://` | | Azure Blob Storage | leave empty, enable `s3proxy.enabled` | `path` | An S3 key pair you set for s3proxy | s3proxy runs in the cluster in front of the Storage Account. **Not tested on a real account** | | On-prem | MinIO, Ceph RGW, or a local provider's S3-compatible object storage | usually `path` | Per system | MinIO allows per-workspace keys | - On S3, GCS and s3proxy, set `objectStorage.tenantKeys: "off"`: one key for the whole bucket, each workspace's data under its own prefix. - With MinIO, `objectStorage.tenantKeys: minio` gives each workspace a key that can only read and write its own area. The MinIO admin key then lives only in `worker`; the chart removes it from `api` and `mcp` automatically. - An alternative on Azure if you would rather not use s3proxy: run your own MinIO on Azure Disk. - Enable versioning on both buckets, and write-once locking (Object Lock, retention, immutability) on the backup bucket. ## Network Pods must be able to reach Postgres, object storage, the AI model server, SMTP, the source databases you plan to connect, and the cluster DNS. In air-gapped mode that is also the complete allow-list; see [Air-gapped mode](/en/docs/self-host/airgapped). ## Related - [Install with Helm](/en/docs/self-host/helm) - [Reference Terraform](/en/docs/self-host/terraform) --- # Reference Terraform (AWS, GCP, Azure) > Sample Terraform modules that build the network, a managed Kubernetes cluster, Postgres, object storage, a shared volume and a secret store, then install the DataxLand Helm chart on AWS, GCP or Azure; a reference template, not yet applied to a real account. These modules are **reference templates**. They pass `terraform fmt -check` and `terraform validate`, but **have not been run with `plan` or `apply` against a real cloud account**. SKU names, regional quotas, least-privilege IAM permissions and timeouts may need adjusting. Your infrastructure team or implementation partner copies the folder for your cloud into your own infrastructure repo and adapts it. DataxLand provides three folders: `aws/`, `gcp/` and `azure/`. Each one reads on its own, with no shared modules. The last step of each folder installs the [Helm chart](/en/docs/self-host/helm) with `helm_release`. ## What each module builds | | AWS | GCP | Azure | | --- | --- | --- | --- | | Network | VPC, public and private subnets per AZ, NAT, S3 gateway endpoint | VPC, subnet with secondary ranges for pods and services, Cloud NAT, Private Service Access | VNet, subnets for AKS, Postgres and private endpoints, private DNS | | Kubernetes | EKS, 3 `m6i.xlarge` nodes (4 vCPU, 16 GB) | Regional GKE, private nodes, Dataplane V2, 3 `e2-standard-4` nodes | AKS, Azure CNI Overlay and Cilium, 3 `Standard_D4s_v5` nodes | | Postgres 16 | RDS Multi-AZ, VPC only, TLS required | Cloud SQL REGIONAL, private IP only, encrypted connections only | Flexible Server ZoneRedundant, VNet integration | | `dx_lake` database | A `psql` Job in the cluster | Created by Terraform | Created by Terraform | | Shared volume | EFS, class `efs-rwx` | Filestore, class `filestore-rwx` (1 TiB minimum) | Azure Files, built-in class `azurefile-csi` | | Object storage | S3, `vhost` | GCS through the S3-compatible API, `path` | Blob through in-cluster s3proxy, `path` | | Object storage keys | IAM user and access key, scoped to the two buckets | Service account and HMAC key, scoped to the two buckets | Random S3 key pair for s3proxy | | Write-once lock for backups (optional) | S3 Object Lock | Retention policy | Immutability policy | | Secret store | Secrets Manager | Secret Manager | Key Vault | | Ingress | Not installed | Not installed | App Routing add-on (can be disabled) | Each module generates the application's secrets, stores them in the cloud secret store and copies them into the Kubernetes Secret the chart reads. Object storage keys are static, one key for the whole bucket: the application does not support IRSA, Workload Identity or Managed Identity. ## Running it The general flow; details are in each folder's `README.md`: ```bash cd aws # or gcp, azure cp terraform.tfvars.example terraform.tfvars # edit for your account terraform init terraform apply -target= # first run: build the cluster first kubectl create namespace dataxland kubectl -n dataxland create secret generic dataxland-license --from-file=license.json terraform import kubernetes_namespace_v1.this dataxland terraform apply ``` The cluster has to exist first because the `kubernetes` and `helm` providers need it. The operator creates the license Secret outside Terraform, before the final `apply`. ### AWS Requires the AWS CLI and permission to create the resources above. ```bash terraform apply -target=aws_eks_node_group.default -target=aws_eks_addon.efs_csi ``` - No ingress controller is installed: use the AWS Load Balancer Controller or one you already run. - The node count is fixed; for autoscaling, install Cluster Autoscaler or Karpenter. - Deletion protection is on for RDS and the cluster; RDS takes a final snapshot on deletion. ### GCP Requires `gcloud auth application-default login`. ```bash terraform apply -target=google_container_node_pool.default gcloud container clusters get-credentials -gke --region ``` - The Filestore `standard` tier needs at least **1 TiB** per PVC. For something smaller: self-managed NFS, or a different tier. - Filestore root directory permissions for uid 10001 have not been verified. ### Azure Requires `az login` and the Owner role (or Contributor plus User Access Administrator) on the subscription. ```bash terraform apply -target=azurerm_kubernetes_cluster.this az aks get-credentials --resource-group -rg --name -aks ``` - Object storage goes through **s3proxy**, which has not been tested with the DataxLand warehouse on a real account. - `azurefile-csi` is SMB-based Azure Files; build performance on SMB has not been measured. For better POSIX behaviour, create an Azure Files NFS class. - The first `apply` may fail with a 403 when writing to Key Vault because the role assignment has not taken effect yet: wait a few minutes and run it again. ## After the run - **Terraform state contains every secret**: use an encrypted remote backend with restricted access. - Copy `DX_BACKUP_ENCRYPTION_KEY` (output `backup_encryption_key`) to offline storage. Lose the key and you lose every backup. - In production, switch to External Secrets Operator reading the secret store directly instead of the Secret Terraform copies; see [Install with Helm](/en/docs/self-host/helm#secrets-from-external-secrets-operator). Extra chart values go in the `helm_extra_values` variable. - The modules don't install an ingress controller, cert-manager, External Secrets Operator or a monitoring stack. ## Related - [Requirements and sizing](/en/docs/self-host/requirements) - [Install with Helm](/en/docs/self-host/helm) --- # Upgrades, backups and restore > Upgrade a self-hosted installation with helm upgrade (the migrate Job runs first), roll back, take daily backups with the worker or a CronJob, rehearse restores and run a real restore with the backup-restore command. The commands below assume the release name `dataxland` in the namespace `dataxland`. Operational commands run in the `worker` pod: ```bash kubectl -n dataxland exec deploy/dataxland-worker -- python -m pipelines.cli ``` ## Upgrading 1. **Read the release notes** for the new version: does it change the schema, can it be rolled back, is there any manual step? 2. **Back up right away** and confirm the new backup has status `ok`: ```bash kubectl -n dataxland exec deploy/dataxland-worker -- python -m pipelines.cli backup kubectl -n dataxland exec deploy/dataxland-worker -- python -m pipelines.cli backup-list ``` 3. Closed network: [copy the new version's images](/en/docs/self-host/airgapped#7-copy-images-into-an-internal-registry) into your internal registry first. 4. **Upgrade**: ```bash helm upgrade dataxland -n dataxland -f values-prod.yaml ``` Helm runs the `migrate` Job first (`python -m pipelines.cli db-migrate`): it creates any missing tables, columns and indexes in Postgres. The Job is safe to run repeatedly; its time limit is set by `migrations.activeDeadlineSeconds` (default 600 seconds). Once the Job finishes, `api`, `web` and `mcp` are replaced gradually, while `worker` stops and starts on the new version: background work (builds, refresh schedules, backups) pauses for a few minutes, dashboards and asking Si keep working. 5. **Check**: `kubectl -n dataxland get pods`, call the `api`'s `/readyz` as during [installation](/en/docs/self-host/helm#6-check-and-sign-in), open a dashboard and look at **Admin → Operations**. If the `migrate` Job fails, Helm stops and the running components stay on the old version. Read the logs with `kubectl -n dataxland logs job/dataxland-migrate`. ### Rolling back `helm rollback dataxland ` is only safe when the new version **has not changed the schema in a way the old version cannot read**; the release notes say so explicitly. If in doubt, the default path is to reinstall the old version and restore the backup taken in step 2. ## Backups A backup contains the Postgres metadata, each workspace's files (uploads, configuration, approvals, encrypted secrets) and the data warehouse of every workspace. Every file is **encrypted with `DX_BACKUP_ENCRYPTION_KEY`** before it is written to the backup bucket. Warehouse data is uploaded once and later backups reference it, so subsequent runs are smaller than the first. ### Schedule By default the `worker` backs up once a day: ```yaml deployment: timezone: Asia/Ho_Chi_Minh objectStorage: backup: enabled: true bucket: dx-backups prefix: "" endpoint: "" # empty = same endpoint as the warehouse at: "02:00" # time in deployment.timezone keep: "7,4,6" # keep 7 daily, 4 weekly, 6 monthly backups ``` To let Kubernetes own the schedule, enable the CronJob. The chart then turns off the `worker`'s own schedule: ```yaml backupCronJob: enabled: true schedule: "0 19 * * *" # 02:00 Vietnam time if the cluster runs on UTC restoreDrill: enabled: true schedule: "0 21 * * 0" # weekly drill ``` Recommendations: - Put the backup bucket in a different region or system from the warehouse bucket. You can use separate keys (`DX_BACKUP_S3_KEY_ID`, `DX_BACKUP_S3_SECRET`) and a separate endpoint (`objectStorage.backup.endpoint`). - Enable versioning and write-once locking (Object Lock, retention, immutability) on the backup bucket. - Never delete the `_objects/` folder in the backup bucket by hand: every backup needs it to restore the warehouse. - Keep the backups of your managed Postgres service as well; the two layers complement each other. ### Keep both keys in two places These two keys are **not part of any backup** and cannot be recovered: - `DX_SECRET_KEY`: decrypts stored source passwords and tokens. Lose it and every data source has to be reconnected. - `DX_BACKUP_ENCRYPTION_KEY`: decrypts backups. Lose it and **every backup encrypted with it becomes unusable**. Keep each key in two places: your company secret store and an offline copy (a printout or an encrypted USB drive in a safe). Keep the two keys apart, managed by different people if possible. ## Restore drills ```bash kubectl -n dataxland exec deploy/dataxland-worker -- python -m pipelines.cli restore-drill kubectl -n dataxland exec deploy/dataxland-worker -- python -m pipelines.cli restore-drill --backup ``` The command restores the newest backup (or the one you specify) into a temporary database and a temporary storage area, compares row counts and the totals of numeric columns with the time of the backup, verifies file checksums, then deletes the temporary copies. **It never touches live data.** The Postgres user needs permission to create databases. Run it at least weekly (or enable `backupCronJob.restoreDrill`). A successful drill also proves the `DX_BACKUP_ENCRYPTION_KEY` you hold is the right one. The metric `dx_backup_last_success_timestamp_seconds` (label `kind`) shows the most recent successful backup and drill. ## Real restore `backup-restore` overwrites data. Pick the backup first: ```bash kubectl -n dataxland exec deploy/dataxland-worker -- python -m pipelines.cli backup-list ``` Parameters of `backup-restore`: | Parameter | Effect | | --- | --- | | `--backup ` | The backup; required | | `--meta` | Load the Postgres metadata; every table in the target database must be empty | | `--tenant ` | Restore this workspace's files and warehouse; can be repeated | | `--all-tenants` | Every workspace in the backup | | `--force` | Overwrite files and replace the existing warehouse | ### One damaged workspace The metadata is intact, only one workspace's warehouse or files are damaged: ```bash kubectl -n dataxland exec deploy/dataxland-worker -- \ python -m pipelines.cli backup-restore --backup --tenant --force ``` Then run a refresh for that workspace to load source data newer than the backup. ### Full restore When you have lost the Postgres metadata, lost the warehouse bucket, or are rebuilding on a new cluster: 1. Create a new Postgres with empty `dx` and `dx_lake` databases. 2. Install the chart at **the same version** as the installation at backup time, with **the same** `DX_SECRET_KEY`, `DX_BACKUP_ENCRYPTION_KEY` and backup location. Keep users out for now: `kubectl -n dataxland scale deploy/dataxland-web --replicas=0` (turn off `web.autoscaling` if it is on). 3. Load the metadata: ```bash kubectl -n dataxland exec deploy/dataxland-worker -- \ python -m pipelines.cli backup-restore --backup --meta ``` 4. Load the files and warehouse of every workspace: ```bash kubectl -n dataxland exec deploy/dataxland-worker -- \ python -m pipelines.cli backup-restore --backup --all-tenants ``` Warehouse data comes from the backup bucket, so the new warehouse bucket can start empty. 5. Restart the components (`kubectl -n dataxland rollout restart deploy`), call `/readyz`, open a workspace's dashboard and compare it with the numbers from before the incident. You can also run `restore-drill --backup `. 6. Reopen `web` (`kubectl -n dataxland scale deploy/dataxland-web --replicas=2`). The next scheduled refresh reloads source data from after the backup; Excel files uploaded after that point must be uploaded again. If `--meta` reports that the target database already has data, or you are unsure which backup to pick, contact DataxLand before going further. ## Related - [Install with Helm](/en/docs/self-host/helm) - [Offline license](/en/docs/self-host/license) - [Security and privacy](/en/docs/security-privacy) --- # Two-factor authentication (2FA) and your account > Turn on 2FA with an authenticator app (TOTP), save 10 recovery codes, turn 2FA off, change your password and sign out other devices. ## Turn on 2FA DataxLand uses 6-digit codes from an authenticator app (TOTP) such as Google Authenticator, Microsoft Authenticator or 1Password. 1. Open **Account** from the user menu. The **Two-factor authentication (2FA)** card shows **Off**. 2. Click **Set up 2FA**. 3. Scan the QR code with your app (or enter the key manually). 4. Enter the 6-digit code it shows and click **Turn on 2FA**. 5. DataxLand shows **10 recovery codes**, once. Store them somewhere safe (a password manager) and click **I've saved the codes**. From your next sign-in, you enter the 6-digit code after your password. If you lose your phone, use a recovery code; each code works once. ## Turn off 2FA Click **Turn off 2FA** and enter your password (for an account that only signs in with Google, enter a 2FA code). If the workspace requires 2FA for your role, turning it off limits you to the account page until you turn it back on. ## Other cards on the account page | Card | Used for | | --- | --- | | Profile | Display name | | Change password | New password, at least 8 characters | | Signed-in devices | **Sign out** one device, or **Sign out of all devices** | | Chat connections | Link Telegram, Slack or Microsoft Teams to ask Si | | Your data | Download your personal data, delete your account | ## Sessions A session lasts at most 30 days and expires after 7 days without use. Five wrong passwords lock sign-in for the account for 15 minutes. ## Related - [Members and roles](/en/docs/workspace/members) - [Security and privacy](/en/docs/security-privacy) - [Export and delete data](/en/docs/workspace/export-delete) --- # Audit log > See who did what in the workspace — sign-ins, members and roles, data access, SSO, MCP tokens, data exports — filter by person, action and date, and export to CSV. Admins and above open **Settings → Audit log**. Filtering and CSV export are included on **every paid plan**; on the Free plan you can still see the latest events in **Members & roles**. ## What is recorded - Members: invitations sent, accepted and revoked; role changes (custom roles included); removals and departures; ownership transfers; 2FA enforcement. - Custom roles: created, edited (permissions added or removed), deleted. - Data access: rules created, edited and deleted; settings changed. - SSO: connections created, edited and deleted; domains added, verified and removed; SSO enforcement turned on or off; SSO sign-ins; just-in-time account creation; break-glass sign-ins; rejected sign-ins. - MCP tokens and embedded-dashboard codes: created, revoked. Workspace exports and audit-log exports. The log never contains passwords, tokens or secrets. ## Filter and export Filter by **actor**, **action** (one action or a whole group, e.g. "Data access (all actions)") and **date range**. **Export CSV** downloads exactly the current filter (up to 100,000 rows, UTF-8 that opens in Excel); the ## Retention Events are kept for **2 years**; IP addresses and browser details are kept for **180 days**, then deleted automatically. Deleting a workspace does not delete its audit log (it is evidence). --- # Row-level data access > Limit people or roles to part of the data — one branch, one sales channel — everywhere DataxLand shows a number, including Si, MCP, chat, reports and alerts. Included from the **Small Business** plan. Admins (or any role with the "Data access" permission) set it up in **Settings → Data access**. ## Rules A rule has a **dimension** from the semantic model (channel, branch, platform…), the **values that may be seen**, and **who it applies to**: members or roles (built-in or custom). - Several rules on the **same dimension** for one person: their values add up (Hanoi + Ho Chi Minh City). - Rules on **different dimensions**: both must hold (Hanoi branch **and** the Shopee channel). - People with no rule: see everything — or nothing, if you turn on **People without any rule see no data**. - By default **Owners and Admins bypass** rules; untick this to restrict them too. Whoever edits rules must be unrestricted themselves (nobody can widen their own access). ## Where it applies The rule's condition is added to **every query** DataxLand runs to compute a number, so totals, period comparisons, top-N lists, ratios and "why" analysis are all computed on the allowed rows only — no number is ever computed on everything and filtered afterwards. | Where | Computed with the permissions of | |---|---| | Dashboards, pages, inspector, queries, "why", report previews | the person viewing | | Si in the app; asking Si in a private chat with the bot (Telegram, Slack, Teams) | the person asking (linked account) | | Telegram groups, Slack channels, Teams channels and group chats | answers only people who are **not restricted** (the whole group sees the answer); restricted people are asked to message the bot privately, unless "Allow answers in group chats based on the asker's access" is on | | MCP | the person who created the token | | Scheduled reports, alerts | the person who created the report or alert (if they leave the workspace, the send is skipped) | Metrics built on a table that **doesn't have** the restricted dimension (e.g. ad spend not split by branch) are **hidden** from restricted people by default; switch the rule to "Still show workspace-wide numbers" if you're fine with them seeing those. Restricted people can't open screens that read **raw data**: data sources, SQL on sources, data profiles, workspace export — and Si doesn't use the [SQL/Python sandbox](/en/docs/ask/sandbox) for them (its extracts take whole tables). ## Downgrading Existing rules keep being enforced (switching them off when a plan ends would expose data); you just can't create or edit them. Every change to rules and settings is recorded in the [audit log](/en/docs/workspace/audit-log). --- # Export and delete data > Export all workspace data (Parquet, CSV, definitions), download your personal data, delete a workspace with a 7-day recovery window and delete your account. Your data is yours: export it at any time, even after you have run out of plan quota. ## Export workspace data 1. Go to **Settings → Data & privacy** (Owner only). 2. On the **Export workspace data** card, tick **Include source data (raw layer)** if you need the data exactly as loaded. 3. Click **Create export**. When it is done, click **Download**. The download link is valid for 15 minutes; the export is kept for 7 days. The `.zip` file contains: | Part | Format | | --- | --- | | README, manifest | Description of the contents | | Workspace configuration, approved mapping (passwords and keys removed) | YAML | | Semantic model, workspace metrics, pages, knowledge, alerts, schedules | JSON | | Standardised tables and metric tables | Parquet; plus CSV for tables up to 100,000 rows | | Audit log (without IP addresses) | JSON | Personal-data columns stay hashed. ## Download your personal data On the **Account** page, card **Your data**, click **Download my data**: one JSON file with your profile, the workspaces you belong to and your roles, your sessions, the security log about you and the questions you asked Si (not the answers, which are workspace data). ## Delete a workspace 1. Go to **Settings → Advanced** (Owner only) and choose to delete the workspace. 2. **Type the workspace name to confirm** and enter **Your password**; for a Google-only account, enter your **2FA code (Google-only accounts)**. 3. Confirm. The workspace waits 7 days before deletion. During that time the Owner can restore it from **Account → Workspaces pending deletion → Restore**. MCP tokens bound only to that workspace are not restored. After 7 days the data is deleted; backups expire on their own within at most 6 months. Sample workspaces are deleted immediately. ## Delete your account 1. Transfer ownership of, or delete, every workspace you own (you cannot delete an account that still owns a workspace). 2. Under **Account → Your data**, click **Send account deletion link**. 3. Open the email (the link is valid for 1 hour) and click **Delete account**. Your MCP tokens are revoked; your name in the logs is replaced with an anonymous ID. ## Related - [Security and privacy](/en/docs/security-privacy) - [Privacy policy](/en/privacy) - [Data processing agreement](/en/dpa) --- # Members and roles > Invite colleagues to a workspace, choose the Admin, Analyst or Viewer role, revoke invitations, transfer ownership, require 2FA and read the security log. ## Roles | Role | Can | | --- | --- | | Owner | Everything: plan and billing, members, deleting the workspace | | Admin | Data sources, reviewing proposals, settings, MCP tokens, activating metrics, approving knowledge | | Analyst | Ask Si, explore data, draft metrics and pages, reports and alerts | | Viewer | View dashboards and shared pages only; cannot ask Si | Each workspace has exactly one Owner. ## Invite members Only the Owner can invite, change roles or remove members. 1. Go to **Settings → Members & roles**. 2. Enter the **Email of the person to invite** and pick a **Role**: Admin, Analyst or Viewer. 3. Click **Send invitation**. Invitations are valid for 7 days. DataxLand sends an email and also shows the link so you can share it yourself (shown only once). Invitations wait in the **Pending invitations** card; click **Revoke** to cancel one. Inviting the same email again replaces the old invitation. Every member and every pending invitation takes one seat of your plan's user allowance. ## Accept an invitation The invitee opens the link and sees the **Workspace invitation** page: - with an existing account: **Sign in to accept the invitation**, then **Accept invitation**; - without one: **Create an account with the invited email**. They must sign in with **exactly the invited email**, and that email must be verified. ## Change roles, remove, leave The members table shows **User**, **Role** and **Last active**. The Owner changes a role or clicks **Delete** to remove a member. Members leave on their own with **Leave workspace**. ## Transfer ownership Click **Transfer ownership** on a member, enter your password (or your 2FA code if the account only signs in with Google) and click **Transfer**. You become an Admin. ## Require 2FA On the **Security** tab (Owner only), tick **Require 2FA for Owners and Admins**. Owners and Admins without 2FA can then only open their account page to turn it on. See [Two-factor authentication](/en/docs/workspace/2fa). ## Security log The **Security log** (Admin and above) records the latest 50 events: sign-ins, invitations, role changes, token creation and more. ## Related - [Two-factor authentication](/en/docs/workspace/2fa) - [Workspaces](/en/docs/concepts/workspace) - [Plans and quotas](/en/docs/billing/quotas) --- # Time zone, currency and formats > Set the workspace time zone, currency and number and date format; what changes when you switch the time zone or currency, and why DataxLand does not convert exchange rates. These settings live in **Settings → General**, card **Time zone, currency and format**. You need the Admin role or above. | Field | Default | What it affects | | --- | --- | --- | | Time zone | Asia/Ho_Chi_Minh (UTC+07:00) | Day, week and month boundaries of every metric; when refresh schedules and reports run | | Currency | VND | Currency labels on dashboards, answers and reports, for example USD or VND | | Number and date format | Vietnam | How numbers and dates are shown: Vietnam, United States, United Kingdom, Singapore, Australia; also the language Si falls back to when a question is too short to tell (Vietnam → Vietnamese, the others → English) | Pick your own time zone and currency when you create the workspace; a US business would choose, say, America/New_York, USD and the United States format, so figures read `$1,234,567.00` and dates `11/16/2026`. ## When you change them - **Time zone or currency**: DataxLand rebuilds the data from scratch and moves schedules and reports to the new time zone. Daily, weekly and monthly numbers and the currency labels change. You cannot save while a job is running; wait for it to finish and save again. - **Format only**: only the display changes; nothing is rebuilt. Click **Save settings**. ## No currency conversion DataxLand does not convert between currencies. If a source carries several currencies (for example Lazada shops in several countries), amounts are summed at their original values; split them by channel or use a separate workspace per currency. ## Weeks and timestamps Weeks always start on Monday. Timestamps are stored in UTC; only business dates follow the workspace time zone. ## Related - [Metrics and the semantic layer](/en/docs/metrics) - [Sync modes and refresh schedules](/en/docs/concepts/sync-modes) - [Workspaces](/en/docs/concepts/workspace) --- # Custom roles > Create roles with exactly the permissions people need (for example managing reports only, or admin rights without touching data sources) on top of the workspace's four built-in roles. The four built-in roles — **Owner, Admin, Analyst, Viewer** — stay as they are ([Members](/en/docs/workspace/members)). On the **Enterprise** plan, the Owner can create more roles in **Settings → Members & roles → Custom roles**. ## Permission catalogue | Level | Permissions | |---|---| | Viewer | View dashboards (dashboards, pages, metrics, data health) — always included | | Analyst | Ask Si (also through Telegram, Slack, Teams); Explore data (queries, "why", inspector, data profiles); Knowledge; Author metrics and pages; View automations | | Admin | Manage data sources (**sees raw data**); Approve the model; Workspace settings; Notification destinations; Manage reports and alerts; MCP tokens; Audit log; Usage and security; Data access | Owner permissions (members, roles, security and SSO, data export, deleting the workspace, billing) can't be granted to a custom role. Each custom role has an **equivalent built-in role** — the lowest built-in role that contains every permission you picked — used for the "require 2FA for Owners and Admins" rule and for seat counting. For example, "Viewer + Manage reports" is equivalent to Admin, so it must also use 2FA when the workspace requires it. ## Assign a role Pick the role in the **Role** column of the member list, or when you send an invitation. Custom roles can also be the default role for [just-in-time SSO provisioning](/en/docs/workspace/sso) and can be used in [data access rules](/en/docs/workspace/data-access). Editing a role's permissions takes effect immediately for everyone who has it. To delete a role, move its members to another role first. If you downgrade below Enterprise, assigned roles stay exactly as they are (no permissions are widened), but you can no longer create or edit them. Creating, editing and deleting roles, and changing a member's role, are recorded in the [audit log](/en/docs/workspace/audit-log). --- # Single sign-on (SSO) > Let staff sign in to DataxLand with their company account through Microsoft Entra ID, Google Workspace, Okta or any OIDC / SAML 2.0 IdP; verify your domain by DNS, provision accounts just in time and enforce SSO. SSO is part of the **Enterprise** plan. The workspace Owner sets it up in **Settings → Security**. ## How it works - The SSO connection belongs to your company's main workspace, while identity follows the **email domain**: anyone with an `@yourcompany.com` address (a verified domain) signs in through your company IdP, whichever workspace they belong to. - Supports **OpenID Connect** (recommended: Entra ID, Google Workspace, Okta, Keycloak, Auth0…) and **SAML 2.0** (SP-initiated). DataxLand verifies the `id_token` signature with the IdP's public keys and SAML signatures with the certificate you paste in (it never trusts a certificate shipped inside the message), along with issuer, audience, expiry and a replay-protection nonce. - **Just-in-time provisioning (JIT)**: someone from your domain signing in for the first time gets an account and joins the workspace with the **default role** (a custom role works too). With JIT off, only people who already have an account or an invitation can get in. ## 1. Create an app in your IdP | IdP | Protocol | Redirect / ACS | Issuer to enter in DataxLand | |---|---|---|---| | Microsoft Entra ID | OIDC (App registrations → Web) | Redirect URI shown on the Security page | Directory (tenant) ID — DataxLand builds `https://login.microsoftonline.com//v2.0` | | Google Workspace | OIDC (Google Cloud → Credentials → OAuth client ID, Web) | Redirect URI | filled in for you; enter your Google Workspace domain to accept company accounts only | | Okta | OIDC (Applications → Web) or SAML | Redirect URI, or ACS URL + Entity ID | Okta domain (e.g. `yourcompany.okta.com`) | | Other IdP | OIDC or SAML 2.0 | as above | Issuer URL (https) | For SAML: turn off assertion encryption, use an email-format NameID (or send an `email` attribute), and download the signing certificate (X.509) to paste into DataxLand. DataxLand's SP metadata is at the **DataxLand metadata** address on the Security page. ## 2. Verify your domain Add the domain, then create a **TXT** record in DNS named `_dataxland.` with the value shown on the page (of the form `dataxland-verification=…`). Click **Check DNS**; DNS changes can take a few minutes to a few hours. Public email domains (gmail.com, outlook.com…) can't be used. A domain belongs to one workspace only. ## 3. Enforce SSO Once you have a verified domain and **one successful SSO sign-in**, turn on **Enforce SSO**: users of the domain can no longer sign in with a password or Google, sign up on their own or reset a password. **Break-glass accounts** (up to 3, two-factor authentication required) can still sign in with a password if the IdP has an outage. **Trust the IdP's multi-factor authentication (MFA enabled at the IdP) for the workspace 2FA requirement**: turn it on when your IdP already enforces MFA; SSO sessions then satisfy the workspace's "require 2FA" rule. ## When someone leaves the company Disable their account in the IdP and they can't start a new session. An open session lasts until it expires (7 days of inactivity); to cut access immediately, remove them from the workspace in **Members & roles**. Automatic sync from the IdP (SCIM) is not part of SSO today. Every change to the configuration and domains, every SSO sign-in, just-in-time account creation and break-glass sign-in is recorded in the [audit log](/en/docs/workspace/audit-log). --- # Cài đặt bằng AI agent > Câu lệnh sao chép sẵn để Claude Code, Cursor hay Codex đọc tài liệu DataxLand và nối MCP giúp bạn. Tài liệu DataxLand có bản Markdown cho AI agent. Dán câu lệnh dưới đây vào agent lập trình trên máy bạn: ```text Đọc https://dataxland.com/vi/docs/mcp.md và https://dataxland.com/llms.txt. Giúp tôi thêm máy chủ MCP "dataxland" vào cấu hình MCP của bạn với token tôi sẽ dán vào, rồi gọi công cụ liệt kê chỉ số để kiểm tra kết nối. Không lưu token vào file trong repo. ``` ## Tài nguyên cho agent | Đường dẫn | Nội dung | | --- | --- | | [/llms.txt](/llms.txt) | Danh mục trang tài liệu và trang chính, theo chuẩn llms.txt | | [/llms-full.txt](/llms-full.txt) | Toàn văn tài liệu dạng Markdown | | `/vi/docs/.md` | Bản Markdown của từng trang tài liệu | ## Lưu ý - Token MCP là bí mật: dán vào ô cấu hình của client, không dán vào chat công khai hay commit. - Agent chỉ đọc được chỉ số đã duyệt; không đọc được bảng thô. --- # Báo cáo và cảnh báo > Gửi báo cáo định kỳ và cảnh báo theo ngưỡng, thay đổi hay bất thường của chỉ số tới Telegram, Slack, Microsoft Teams hoặc Google Sheets; nối đích nhận thông báo. Trang **Báo cáo và cảnh báo** (nhóm **Dữ liệu và kết nối**) gửi số tới nơi đội bạn đang làm việc: Telegram, Slack, Microsoft Teams hoặc Google Sheets. Cần vai trò Phân tích trở lên; nối đích nhận cần Quản trị. ## 1. Nối đích nhận thông báo Vào **Cài đặt → Thông báo**, thẻ **Đích nhận thông báo**. | Đích | Cách nối | | --- | --- | | Telegram | Điền **Tên đích Telegram** (ví dụ Nhóm Kinh doanh), bấm **Nối Telegram**, rồi mở Telegram và bấm **Start** với bot. Gửi vào nhóm: thêm bot vào nhóm và gửi tin `/start `. Mã hết hạn sau 15 phút | | Slack | Mở **Cách tạo Slack app (5 phút)**: tạo app từ manifest có sẵn, cài vào Slack workspace, chép **Bot token** (`xoxb-…`), mời bot vào kênh (`/invite @DataxLand`) và chép **ID kênh**. Điền **Tên đích Slack**, token, ID kênh, bấm **Nối Slack**; DataxLand gửi một tin thử | | Microsoft Teams | Thêm ứng dụng DataxLand vào kênh, nhóm hoặc chat riêng trên Teams. Điền **Tên đích Microsoft Teams**, bấm **Nối Microsoft Teams**, rồi trong cuộc trò chuyện đó gửi `@DataxLand connect ` (hết hạn sau 15 phút); trang tự chuyển sang **Đang hoạt động**. Xem [Microsoft Teams](/vi/docs/channels/teams) | | Google Sheets | Dán **Khóa service account (JSON)**, chọn **Cách ghi**: **Ghi đè** hoặc **Thêm dòng**, bấm **Nối Google Sheets** (gói Doanh nghiệp nhỏ trở lên) | Thẻ **Nhật ký gửi** ghi 50 lần gửi gần nhất trên mọi kênh: Telegram, Slack, Microsoft Teams, Google Sheets và email. ## 2. Báo cáo định kỳ 1. Ở thẻ **Báo cáo định kỳ**, bấm **Tạo báo cáo**. Hộp **Lên lịch báo cáo** mở ra (cũng mở được từ **Chia sẻ → Lên lịch báo cáo** trên dashboard). 2. Điền **Tên báo cáo**, chọn **Kỳ số liệu**: Hôm qua, 7 ngày qua, Tuần trước, Tháng trước. 3. **Nội dung**: **Một trang dashboard** hoặc **Tự chọn chỉ số**. 4. **Gửi tới**: một đích đã nối. 5. **Tần suất**: Hằng ngày, Hằng tuần (chọn **Thứ**), Hằng tháng (chọn **Ngày trong tháng**, 1–28), và **Giờ chạy** theo múi giờ workspace. 6. Bấm **Xem trước** để xem nội dung, **Gửi ngay** để thử. ## 3. Cảnh báo 1. Ở thẻ **Cảnh báo**, bấm **Tạo cảnh báo** (hoặc **Chia sẻ → Đặt cảnh báo**). Hộp **Đặt cảnh báo** mở ra. 2. Chọn **Chỉ số**, đặt **Tên cảnh báo**, tùy chọn **Lọc** (ví dụ một kênh). 3. **Kỳ**: theo ngày, tuần hoặc tháng. 4. **Điều kiện**: - **Vượt ngưỡng**: ví dụ tỷ lệ hoàn trên 8%; - **Thay đổi so với kỳ trước**: ví dụ doanh thu giảm hơn 20%; - **Bất thường**: lệch khỏi mức thường thấy, chỉnh **Độ nhạy**; đánh dấu **Báo cả hai chiều** để báo cả tăng và giảm. 5. **Chờ giữa hai lần báo (giờ)**: mặc định 24. 6. Bấm **Chạy thử** để xem với số hiện tại. Cảnh báo được kiểm sau mỗi lần dữ liệu làm mới, tối đa một lần mỗi kỳ. Thẻ **Gợi ý** đề xuất cảnh báo hay dùng; bấm **Bật** hoặc **Tùy chỉnh**. Thẻ **Lịch sử** ghi các lần đã gửi. ## Giới hạn theo gói | Gói | Cảnh báo | Báo cáo | Tần suất báo cáo | Đích | | --- | --- | --- | --- | --- | | Miễn phí | 0 | 1 | Hằng tuần | Telegram, Slack, Teams | | Khởi đầu | 5 | 20 | Ngày, tuần, tháng | Telegram, Slack, Teams | | Doanh nghiệp nhỏ trở lên | Không giới hạn | Không giới hạn | Mọi tần suất | Telegram, Slack, Teams, Google Sheets | ## Hỏi Si trong kênh chat Báo cáo đi một chiều. Để hỏi Si ngay trong Slack, Teams hay Telegram, xem [Slack](/vi/docs/channels/slack), [Microsoft Teams](/vi/docs/channels/teams) và [Telegram](/vi/docs/channels/telegram). ## Liên quan - [Gói và hạn mức](/vi/docs/billing/quotas) - [Chỉ số và lớp ngữ nghĩa](/vi/docs/metrics) - [Cảnh báo và báo cáo trên trang tính năng](/vi/platform/alerts-reports) --- # Kiến trúc > Dữ liệu đi từ nguồn qua ba lớp tới kho riêng của từng workspace; build, kiểm tra, công bố; và cách dashboard, Si, MCP đọc số qua một cổng chỉ số. ## Luồng dữ liệu 1. **Nạp**: dữ liệu nguồn vào lớp thô, giữ nguyên trạng; DataxLand không sửa, không lọc dữ liệu gốc. Cột thông tin cá nhân được băm ngay tại đây trừ khi bạn cho phép lưu gốc. 2. **Chuẩn hóa**: mỗi bảng nguồn thành một mô hình giữ tên cột gốc, rồi ghép về mô hình chuẩn của ngành (đơn hàng, dòng đơn, sản phẩm, phí, hoàn hàng, quảng cáo…) theo ánh xạ đã duyệt. 3. **Mô hình chỉ số**: bảng phục vụ chỉ số của từng gói ngành × phòng ban. ## Một lần build Mỗi lần build (sau khi duyệt, khi làm mới) chạy các bước: mở kho build, nạp, sinh model, biến đổi, kiểm tra chất lượng, đối chiếu số, công bố. Mỗi bước chạy lại được an toàn; mỗi workspace chỉ có một lần chạy cùng lúc. Kiểm tra mức chặn hoặc số không khớp thì không công bố. Xem [Số có kiểm tra](/vi/docs/data-quality). ## Kho dữ liệu Mỗi workspace có kho riêng: file Parquet trên object storage, danh mục bảng riêng theo workspace, khóa lưu trữ riêng chỉ dùng cho workspace đó. Build ghi vào kho build của lần chạy; dashboard, Si và MCP chỉ đọc bản đã công bố. ## Một định nghĩa chỉ số Dashboard, Si, báo cáo, cảnh báo và MCP chỉ lấy số qua **một cổng chỉ số** trên lớp ngữ nghĩa. Không có SQL trong giao diện, file dashboard hay công cụ của Si. Xem [Chỉ số và lớp ngữ nghĩa](/vi/docs/metrics). ## Si đề xuất, người duyệt Si đọc mẫu đã che và đề xuất ánh xạ; mô hình dữ liệu do DataxLand sinh từ kế hoạch bạn duyệt. Không build khi workspace chưa được duyệt. Xem [Si](/vi/docs/si). ## Một bộ công cụ cho mọi nơi Si trong ứng dụng, Si trong Slack, Telegram và Microsoft Teams, và [máy chủ MCP](/vi/docs/mcp) dùng cùng một bộ công cụ chỉ đọc. Công cụ chỉ ghi nhật ký và bản nháp chờ duyệt (đề xuất chỉ số, ô ghim). ## Liên quan - [Bảo mật và quyền riêng tư](/vi/docs/security-privacy) - [Cách đồng bộ và lịch làm mới](/vi/docs/concepts/sync-modes) - [Nền tảng](/vi/platform) --- # Kết nối dữ liệu > Các loại nguồn DataxLand nhận — file Excel, sàn thương mại điện tử, PostgreSQL, BigQuery, REST API và thư viện connector — và cách thêm nguồn vào workspace. Dữ liệu từ mọi nguồn được **chép về kho riêng của workspace**; dashboard không truy vấn trực tiếp vào nguồn của bạn. ## Loại nguồn | Loại | Cách nối | Hướng dẫn | | --- | --- | --- | | File Excel (.xlsx) | Tải lên, mỗi sheet một bảng, kèm sheet `data_dictionary` | [File Excel](/vi/docs/sources/excel) | | PostgreSQL | Thông tin kết nối chỉ đọc; toàn bộ, tăng dần hoặc CDC | [PostgreSQL](/vi/docs/sources/postgres) | | BigQuery | Khóa service account; nạp tăng dần, có giới hạn dung lượng quét | [BigQuery](/vi/docs/sources/bigquery) | | Shopee, TikTok Shop, Lazada | Đăng nhập trên trang của sàn (OAuth), không dán mật khẩu | [Shopee](/vi/docs/sources/shopee), [TikTok Shop](/vi/docs/sources/tiktok-shop), [Lazada](/vi/docs/sources/lazada) | | Phần mềm có REST API trả JSON (POS, CRM, kho, ERP nội bộ) | Khai báo địa chỉ, xác thực, endpoint, phân trang | [REST API tùy biến](/vi/docs/sources/rest-api) | | Quảng cáo, CRM, thanh toán, phân tích… | Hơn 560 connector trong thư viện | [Thư viện connector](/vi/docs/sources/connector-library) | Gói **Miễn phí** chỉ nhận một file Excel. Các gói trả phí nhận mọi loại nguồn và làm mới theo lịch. Xem [Gói và hạn mức](/vi/docs/billing/quotas). ## Nguồn đầu tiên: khi tạo workspace Trang **Tạo workspace** hiện thư viện nguồn ngay từ đầu. Chọn nguồn, nhập **Tên workspace** rồi bấm **Tạo workspace và đọc dữ liệu**. Các bước tiếp theo nằm ở [Bắt đầu nhanh](/vi/docs/quickstart). ## Thêm nguồn vào workspace đã có 1. Vào **Nguồn dữ liệu** (nhóm **Dữ liệu và kết nối**). Cần vai trò Quản trị hoặc Chủ sở hữu. 2. Ở thẻ **Các nguồn của workspace**, bấm **Thêm nguồn**. **Thư viện nguồn dữ liệu** mở ra. 3. Tìm trong ô **Tìm connector** hoặc lọc theo nhóm. Bấm **Chọn** trên một hay nhiều connector rồi **Tiếp tục**. 4. Điền từng form. Đặt **Tên nguồn** (chữ thường không dấu, số, dấu gạch dưới; bắt đầu bằng chữ; tối đa 16 ký tự). Nếu nguồn mới liên quan tới nguồn đã có, đánh dấu **Nguồn mới có liên quan đến nguồn đã có**. 5. Bấm **Kiểm tra kết nối**; thấy **Kết nối được** là đúng. 6. Ở **Xem lại trước khi thêm**, bấm **Thêm N nguồn**. Sàn thương mại điện tử được kết nối sau cùng, trên trang của sàn. 7. Sau khi đọc, bạn xác nhận lại cột thông tin cá nhân rồi Si đề xuất lại. Dashboard hiện tại vẫn xem được trong lúc đó. Mỗi workspace có tối đa 8 nguồn (gói Khởi đầu: 3). Bấm **Bỏ** để gỡ một nguồn; DataxLand đọc lại dữ liệu và đưa workspace về bước chọn cột cần che. ## Trang Nguồn dữ liệu | Thẻ | Dùng để | | --- | --- | | Các nguồn của workspace | Thêm, gỡ nguồn; khai báo quan hệ giữa nguồn | | Lịch làm mới dữ liệu | Đặt tần suất làm mới tự động, xem [Cách đồng bộ](/vi/docs/concepts/sync-modes) | | Cách đồng bộ | Toàn bộ, tăng dần hoặc CDC theo từng bảng | | Thay file | Với Excel: tải file mới và làm mới | | Kết nối và bảng | Với PostgreSQL, BigQuery: sửa kết nối, chọn bảng | Nút **Làm mới dữ liệu** ở đầu trang chạy làm mới ngay. ## Mật khẩu và khóa Ô mật khẩu được mã hóa khi lưu và không hiển thị lại. Thẻ nguồn ghi **Đã lưu mật khẩu** hoặc **Chưa lưu mật khẩu**. Thông tin cá nhân trong dữ liệu được che và băm, xem [Che thông tin cá nhân](/vi/docs/review/pii). ## Liên quan - [Cách đồng bộ và lịch làm mới](/vi/docs/concepts/sync-modes) - [Duyệt đề xuất và build](/vi/docs/review/mapping) - [Danh mục connector](/vi/connectors) --- # Số có kiểm tra > Kiểm tra chất lượng dữ liệu sau mỗi lần build, đối chiếu số với nguồn trước khi công bố, trang Sức khỏe dữ liệu và cách DataxLand ẩn chỉ số khi số vô lý. ## Kiểm tra sau mỗi build Mỗi lần build chạy bộ kiểm tra dữ liệu: khóa không trùng, không rỗng, quan hệ giữa bảng, giá trị hợp lệ. Mỗi kiểm tra có mức **Chặn** hoặc **Cảnh báo**: - **Cảnh báo**: dashboard vẫn công bố; dòng lỗi được ghi lại để bạn sửa ở nguồn. - **Chặn**: lần build không được công bố. Dashboard vẫn hiện bản công bố trước (nếu có). Test lỗi không làm hỏng build: kết quả được lưu theo từng test, kèm dòng nguồn bị lỗi. ## Trang Sức khỏe dữ liệu Nhiều gói có trang **Sức khỏe dữ liệu** trong nhóm **Dữ liệu và kết nối**. Ô **Kiểm tra chất lượng dữ liệu** ghi tổng số kiểm tra, số chưa đạt và số ở mức chặn; mỗi kiểm tra có trạng thái **Đạt**, **Lỗi** hoặc **Không chạy được**. ## Đối chiếu số trước khi công bố Trước bước **Công bố**, DataxLand so vài tổng quan trọng (số đơn, doanh thu gộp) giữa dữ liệu đã nạp và kho đã build. Lệch thì lần build dừng lại, không công bố số sai; tiến trình ghi bước bị lỗi. ## Ẩn khi số vô lý Khi dữ liệu cho ra số vô lý, ví dụ tổng phát sinh Nợ và Có của sổ cái không bằng nhau, chỉ số liên quan bị tạm ẩn kèm lý do ("Chưa tính được: …") thay vì hiện một con số sai. Ở bước **Duyệt và build**, mục **Chỉ số chưa có** liệt kê các chỉ số này; chúng không ảnh hưởng tới các chỉ số còn lại. ## Kho build và kho đã công bố Build ghi vào kho riêng của lần chạy; dashboard, Si và MCP chỉ đọc kho đã công bố. Bạn không bao giờ thấy số của một lần build đang chạy dở. ## Ô "Chưa đầy đủ" Trên dashboard, ô có nhãn **Chưa đầy đủ** khi độ phủ dữ liệu của chỉ số dưới 100%; di chuột lên nhãn để xem tỷ lệ. Số đó có thể lệch so với thực tế. Dòng **Dữ liệu đến** cho biết ngày mới nhất có số. Ô có dòng **Không áp dụng bộ lọc** khi bộ lọc trang không hợp với chỉ số đó. ## Liên quan - [Chỉ số và lớp ngữ nghĩa](/vi/docs/metrics) - [Duyệt đề xuất và build](/vi/docs/review/mapping) - [Số có kiểm tra trên trang tính năng](/vi/platform/data-quality) --- # Câu hỏi thường gặp và xử lý sự cố > Cách xử lý lỗi thường gặp khi tải Excel, kết nối nguồn, duyệt, build, hỏi Si, nối Slack/Telegram, MCP và khi chạm hạn mức gói. ## Dữ liệu và nguồn **File Excel bị từ chối.** Kiểm tra: đúng `.xlsx` (không phải `.xls`, `.csv`), không quá 50 MB, mỗi sheet tối đa 200.000 dòng, dòng 1 không có ô trống, không có hai cột cùng tên. Thông báo lỗi ghi tên sheet. Xem [File Excel](/vi/docs/sources/excel). **Thiếu sheet `data_dictionary` có sao không?** DataxLand vẫn đọc và suy ra kiểu, ý nghĩa cột từ dữ liệu; Si sẽ hỏi nhiều hơn. Nếu có sheet này thì phải đủ cột `table_name`, `column_name`, `data_type`, `description`. **Không chọn được PostgreSQL, BigQuery hay connector.** Gói Miễn phí chỉ nhận một file Excel. Nâng cấp lên Khởi đầu trở lên. Xem [Gói và hạn mức](/vi/docs/billing/quotas). **Nút sàn ghi "Chưa cấu hình khóa ứng dụng".** Kết nối sàn đó chưa mở trên máy chủ này. Tạm dùng file xuất từ sàn với [File Excel](/vi/docs/sources/excel). **Kiểm tra kết nối báo "Không kết nối được".** Kiểm tra máy chủ, cổng, tài khoản, mật khẩu, SSL; database có chặn IP không; với connector, khóa API còn hạn và đủ quyền. **CDC báo "Chưa đạt".** Xử lý từng mục theo bảng ở [PostgreSQL](/vi/docs/sources/postgres#cdc), rồi bấm **Kiểm tra điều kiện CDC** lại. **Lịch 15 hoặc 30 phút không chạy.** Hai tần suất này cần gói Doanh nghiệp nhỏ trở lên và mọi nguồn đồng bộ tăng dần hoặc CDC. Lịch không thuộc gói bị bỏ qua kèm lý do. ## Duyệt và build **Không thấy nút Duyệt.** Duyệt cần vai trò Quản trị hoặc Chủ sở hữu. **Không duyệt được: "Mọi dòng phải có trạng thái chuẩn".** Mở **Duyệt đề xuất → Trạng thái** và chọn trạng thái chuẩn cho mọi giá trị trạng thái của nguồn. **Build "Bị chặn".** Một kiểm tra mức chặn không đạt, hoặc số đã build không khớp nguồn. Dashboard vẫn hiện bản công bố trước. Xem [Số có kiểm tra](/vi/docs/data-quality), sửa dữ liệu nguồn rồi làm mới. **Một chỉ số không có trên dashboard.** Xem mục **Chỉ số chưa có** ở bước **Duyệt và build**: thường do thiếu dữ liệu (ví dụ chưa có giá vốn) hoặc số vô lý bị tạm ẩn. ## Hỏi Si **Si trả lời "Không trả lời được câu này".** Chỉ số cần thiết chưa có, hoặc câu hỏi chưa rõ. Hỏi cụ thể hơn (chỉ số, kỳ, chiều), xem [Sổ tay chỉ số](/vi/docs/metrics), hoặc tạo [chỉ số của workspace](/vi/docs/metrics/workspace-metrics). **Si hiểu sai một từ của doanh nghiệp.** Thêm mục **Thuật ngữ** ở trang [Kiến thức](/vi/docs/metrics/knowledge) và duyệt nó. **Không thấy Hỏi Si.** Vai trò Xem không hỏi Si được; nhờ Chủ sở hữu đổi vai trò sang Phân tích. **"Đã hết câu hỏi cho Si tháng này".** Chờ kỳ sau, mua thêm 500 câu hoặc nâng cấp. Dashboard và báo cáo vẫn chạy. ## Slack, Telegram, MCP **Bot không trả lời trong nhóm.** Trong nhóm, bot chỉ đọc `/ask`, tin nhắc tên bot và tin trả lời vào tin của bot. Nhóm phải được gắn workspace bằng `/ws`, và người hỏi phải nối tài khoản. Xem [Telegram](/vi/docs/channels/telegram), [Slack](/vi/docs/channels/slack). **Mã nối bị từ chối.** Mã dùng một lần, hết hạn sau 10 phút và chỉ nhận trong chat riêng với bot. Tạo mã mới. **Không tạo được token MCP.** MCP cần gói Doanh nghiệp nhỏ trở lên và vai trò Quản trị. Token chỉ hiện một lần; mất thì thu hồi và tạo token mới. Xem [Máy chủ MCP](/vi/docs/mcp). ## Tài khoản **Mất điện thoại có ứng dụng 2FA.** Đăng nhập bằng một trong 10 mã khôi phục, rồi cài lại 2FA. Xem [Xác thực hai lớp](/vi/docs/workspace/2fa). **Lỡ xóa workspace.** Chủ sở hữu khôi phục trong 7 ngày ở **Tài khoản → Workspace đang chờ xóa → Khôi phục**. ## Liên quan - [Bảng thuật ngữ](/vi/docs/glossary) - [Bắt đầu nhanh](/vi/docs/quickstart) - [Liên hệ](/vi/contact) --- # Bảng thuật ngữ > Nghĩa của các từ dùng trong DataxLand — workspace, Si, đề xuất, ánh xạ, lớp ngữ nghĩa, mức xác nhận, build, công bố, CDC, PII, MCP và các từ khác. | Thuật ngữ | Nghĩa | | --- | --- | | Ánh xạ | Cột nguồn nào ứng với trường nào trong mô hình chuẩn (mã đơn, ngày, số tiền, phí…). Si đề xuất, người duyệt | | Bản đã duyệt | Phiên bản đề xuất đã được Quản trị duyệt; build chạy trên bản này | | Build | Lần dựng kho dữ liệu từ nguồn và bản đã duyệt: nạp, biến đổi, kiểm tra, công bố | | CDC (đọc log) | Đồng bộ PostgreSQL bằng nhật ký thay đổi, thấy cả dòng bị sửa và xóa. Xem [Cách đồng bộ](/vi/docs/concepts/sync-modes) | | Chặn mềm | Khi chạm hạn mức gói, chỉ chặn tạo thêm, không chặn xem | | Chiều | Cách tách một con số: kênh, sản phẩm, ngày… | | Chỉ số | Con số có định nghĩa, đơn vị, phiên bản: doanh thu thuần, lãi sau phí… | | Chỉ số của workspace | Chỉ số do workspace tự định nghĩa, mã `ws.`, kiểm số trước khi bật | | Chuẩn, Đã duyệt, Chưa xác nhận | Ba [mức xác nhận](/vi/docs/metrics) của một con số: của gói, của workspace đã duyệt, câu trả lời khám phá | | Công bố | Bước cuối của build: bản mới thay bản cũ cho dashboard, Si, MCP | | Connector | Bộ nối một phần mềm nguồn. Xem [Thư viện connector](/vi/docs/sources/connector-library) | | Copilot | Tên cũ của Si · Phân tích ngữ cảnh; ứng dụng không còn dùng tên này | | Đề xuất | Bản Si soạn: mô hình nghiệp vụ, ánh xạ, trạng thái, câu hỏi, chỉ số, bố cục | | Đích nhận thông báo | Nơi nhận báo cáo, cảnh báo: Telegram, Slack, Microsoft Teams, Google Sheets | | Gói ngành × phòng ban | Bộ mô hình chuẩn, chỉ số, dashboard cho một ngành và một phòng ban | | Hạn mức | Giới hạn của gói: nguồn, dung lượng, câu hỏi cho Si… Xem [Gói và hạn mức](/vi/docs/billing/quotas) | | Kho đã công bố | Bản kho dữ liệu dashboard, Si, MCP đang đọc | | Kiến thức | Hướng dẫn, thuật ngữ, sự kiện giúp Si hiểu doanh nghiệp. Xem [Kiến thức](/vi/docs/metrics/knowledge) | | Lớp ngữ nghĩa | Mô tả bảng, quan hệ, chiều, bộ lọc để mọi câu hỏi và ô dashboard được dịch thành truy vấn đúng | | Loại hình dữ liệu | Ngành và phòng ban Si chọn cho workspace | | MCP | Model Context Protocol: chuẩn để AI agent bên ngoài gọi công cụ. Xem [Máy chủ MCP](/vi/docs/mcp) | | Mô hình chuẩn | Các bảng chung của ngành (đơn hàng, dòng đơn, sản phẩm, phí, hoàn hàng…) mà dữ liệu nguồn được đổi về | | PII | Thông tin cá nhân (tên, điện thoại, email, địa chỉ). Bị che với Si và băm trong kho | | Si | Trợ lý dữ liệu AI của DataxLand: Si phân tích ngữ cảnh và Si hỏi đáp. Xem [Si](/vi/docs/si) | | Suy nghĩ sâu | Chế độ hỏi Si phân tích nhiều bước, chậm hơn, tính 3 câu hỏi | | Tăng dần | Đồng bộ chỉ dòng mới hoặc đổi theo cột con trỏ | | Token MCP | Khóa có hạn để agent bên ngoài đọc chỉ số; chỉ hiện một lần | | Trang của workspace | Trang ô tự chọn, riêng hoặc dùng chung. Xem [Trang của workspace](/vi/docs/dashboards/pages) | | Workspace | Đơn vị dữ liệu, thành viên và gói. Xem [Workspace](/vi/docs/concepts/workspace) | --- # Tài liệu DataxLand > Bắt đầu với DataxLand — kết nối dữ liệu, duyệt đề xuất của Si, đọc dashboard đã kiểm số và hỏi Si. DataxLand là đội dữ liệu AI cho doanh nghiệp chưa có đội dữ liệu: nhận mọi dữ liệu doanh nghiệp (Excel, database và hơn 500 nguồn) ở mọi ngành và phòng ban, tự dựng dashboard đã kiểm số, và để bạn hỏi **Si**, trợ lý dữ liệu AI. Si tự hiểu dữ liệu và hỏi lại khi chưa rõ; bạn duyệt rồi mới build. ## Đọc gì trước | Bạn muốn | Trang | | --- | --- | | Xem DataxLand làm được gì trong 5 phút, rồi có dashboard đầu tiên | [Bắt đầu nhanh](/vi/docs/quickstart) | | Hiểu workspace, trạng thái và vai trò | [Workspace](/vi/docs/concepts/workspace) | | Nối Excel, database, API, sàn hoặc connector | [Kết nối dữ liệu](/vi/docs/connect-data) | | Duyệt cách Si hiểu dữ liệu trước khi build | [Duyệt đề xuất và build](/vi/docs/review/mapping) | | Hỏi Si trong ứng dụng | [Hỏi Si trong ứng dụng](/vi/docs/ask/app) | | Biết một con số được tính thế nào | [Chỉ số và lớp ngữ nghĩa](/vi/docs/metrics) | | Nhận báo cáo, cảnh báo, hỏi Si trong Slack hoặc Telegram | [Báo cáo và cảnh báo](/vi/docs/alerts-reports) | | Nối Claude, Cursor hay agent riêng | [Máy chủ MCP](/vi/docs/mcp) | | Mời đồng nghiệp, bật 2FA | [Thành viên và vai trò](/vi/docs/workspace/members) | | Xem giới hạn của gói | [Gói và hạn mức](/vi/docs/billing/quotas) | ## Ba lớp dữ liệu Dữ liệu đi qua ba lớp: **nạp** (giữ nguyên trạng), **chuẩn hóa** (đổi về mô hình chuẩn của ngành) và **mô hình chỉ số** (chỉ số có định nghĩa và phiên bản). Si đề xuất cách hiểu và ánh xạ dữ liệu; bạn duyệt rồi mới build. Chi tiết ở [Kiến trúc](/vi/docs/architecture). ## Gặp vấn đề Xem [Câu hỏi thường gặp và xử lý sự cố](/vi/docs/faq) và [Bảng thuật ngữ](/vi/docs/glossary). ## Cho AI agent Mỗi trang tài liệu có bản Markdown: thêm `.md` vào cuối đường dẫn (ví dụ [/vi/docs/mcp.md](/vi/docs/mcp.md)). Danh mục cho agent ở [/llms.txt](/llms.txt), toàn văn ở [/llms-full.txt](/llms-full.txt). Xem [Cài đặt bằng AI agent](/vi/docs/agent-setup). --- # Máy chủ MCP > Nối Claude Desktop, Claude Code, Cursor hoặc AI agent của bạn với chỉ số đã duyệt của workspace qua Model Context Protocol — token, quyền, cấu hình client và công cụ. DataxLand có máy chủ [Model Context Protocol](https://modelcontextprotocol.io). Agent bên ngoài dùng **cùng bộ công cụ với Si**: đọc chỉ số, chiều, bộ lọc, kỳ và so sánh qua lớp ngữ nghĩa. Mặc định không có công cụ chạy SQL tự do; token được cấp thêm quyền `explore:run` có sandbox khám phá (kết quả luôn Chưa xác nhận, xem [Si viết và chạy SQL/Python](/vi/docs/ask/sandbox)). ## 1. Tạo token MCP cần gói **Doanh nghiệp nhỏ** trở lên và vai trò Quản trị trở lên. 1. Vào **Cài đặt → Tích hợp**, mục **Token MCP**. 2. Ở thẻ **Tạo token**, điền **Nhãn** (ví dụ "Claude của Lan"). 3. **Quyền**: chọn **metrics:read – đọc chỉ số** cho hỏi đáp; thêm **ops:read – xem vận hành** nếu agent cần xem tình trạng build (không có giá trị dữ liệu). 4. **Workspace**: workspace token được đọc. Gói Doanh nghiệp chọn được nhiều workspace cho một token. 5. **Hết hạn sau (ngày)**: mặc định 90, tối đa 365. 6. Bấm **Tạo token**. Token (bắt đầu bằng `dxp_`) chỉ hiện **một lần**: bấm **Sao chép** ngay. DataxLand chỉ lưu bản băm. Danh sách **Token đã tạo** ghi trạng thái **Đang dùng**, **Hết hạn** hoặc **Đã thu hồi**. Bấm **Thu hồi** để vô hiệu ngay. ## 2. Cấu hình client Máy chủ dùng Streamable HTTP tại đường dẫn `/mcp`, xác thực bằng header `Authorization: Bearer `. Địa chỉ dưới đây là của bản chính thức; bản tự triển khai dùng địa chỉ máy chủ MCP của bạn. ### Cursor File `~/.cursor/mcp.json` (hoặc `.cursor/mcp.json` trong dự án, không commit token): ```json { "mcpServers": { "dataxland": { "url": "https://app.dataxland.com/mcp", "headers": { "Authorization": "Bearer " } } } } ``` ### Claude Code ```bash claude mcp add --transport http dataxland https://app.dataxland.com/mcp \ --header "Authorization: Bearer " ``` ### Claude Desktop Claude Desktop nối máy chủ MCP từ xa có header qua cầu `mcp-remote` (cần Node.js). Mở **Settings → Developer → Edit Config** và thêm: ```json { "mcpServers": { "dataxland": { "command": "npx", "args": ["-y", "mcp-remote", "https://app.dataxland.com/mcp", "--header", "Authorization:${DX_MCP_TOKEN}"], "env": { "DX_MCP_TOKEN": "Bearer " } } } } ``` Khởi động lại Claude Desktop. ## 3. Thử Hỏi agent: "Dùng DataxLand, liệt kê các chỉ số của workspace", rồi "Lãi sau phí tháng trước theo kênh". ## Công cụ | Quyền | Công cụ | | --- | --- | | metrics:read | `list_metrics`, `describe_metric`, `query_metric`, `query_semantic`, `get_semantic_model`, `explain_change`, `get_business_model`, `search_knowledge` | | ops:read | `get_health`, `list_runs`, `get_run`, `list_metric_requests` | | explore:run (cấp riêng, mặc định không có) | `sandbox_tables`, `run_sql`, `run_python` — SQL/Python chạy trong sandbox cách ly trên bản sao chỉ đọc không có thông tin cá nhân; biểu đồ trả dạng ảnh; mỗi lần chạy tính 1 câu hỏi cho Si; gói Doanh nghiệp nhỏ trở lên | Token nhiều workspace (gói Doanh nghiệp) có thêm công cụ `list_tenants`, và mỗi công cụ nhận tham số `tenant` để chọn workspace. ## An toàn và giới hạn - Mỗi lời gọi được ghi nhật ký kèm token và công cụ. - Token nhiều workspace phải chọn workspace trong mỗi lời gọi; máy chủ kiểm tra token có quyền với workspace đó. - Công cụ vận hành không trả giá trị ô dữ liệu; không công cụ nào trả thông tin cá nhân người mua. - Tối đa 60 lời gọi mỗi phút mỗi token, 120 mỗi phút mỗi người dùng; vượt thì nhận lỗi giới hạn tốc độ. - Token là bí mật: không dán vào chat công khai hay commit vào repo. ## Liên quan - [Cài đặt bằng AI agent](/vi/docs/agent-setup) - [Chỉ số và lớp ngữ nghĩa](/vi/docs/metrics) - [MCP trên trang tính năng](/vi/platform/mcp) --- # Bắt đầu nhanh > Từ đăng ký tới workspace mẫu theo ngành, dashboard đầu tiên trên dữ liệu của bạn và câu hỏi đầu tiên cho Si. Trang này đi hết một vòng: xem thử trên dữ liệu mẫu, rồi làm lại với dữ liệu của bạn. Trong ứng dụng, phần phân tích ngữ cảnh và màn hỏi đáp **Hỏi Si** đều là Si (xem [Si](/vi/docs/si)). ## 1. Đăng ký (2 phút) 1. Mở [app.dataxland.com/signup](https://app.dataxland.com/signup), đăng ký bằng email hoặc Google. 2. Bấm liên kết xác thực trong email. Khung **Tiến độ bắt đầu** ở trang chính đếm các bước còn lại. ## 2. Xem thử với workspace mẫu (3 phút) Màn **Chào mừng đến với DataxLand** có hai lựa chọn. Ở thẻ **Xem ngay với dữ liệu mẫu**, chọn **Ngành của bạn** và **Bộ dữ liệu mẫu** (gợi ý sẵn theo ngành bạn đến từ trang giải pháp, nếu có) rồi bấm **Mở workspace mẫu**: dashboard đã dựng sẵn trên dữ liệu giả lập, có băng **Workspace demo** ở đầu trang. Workspace mẫu không chiếm chỗ trong số workspace của gói; bạn xóa nó bất kỳ lúc nào bằng **Xóa workspace demo**. Muốn xem Si đề xuất từ đầu thì vào thư viện **Dữ liệu mẫu theo ngành** và chọn **Để AI đề xuất** thay cho **Dùng thử**. ## 3. Tạo workspace với dữ liệu của bạn (5 phút) 1. Bấm **Tạo workspace của tôi** (hoặc mở `/new`). Trang **Tạo workspace** hiện thư viện nguồn. 2. Nhập **Tên workspace**. 3. Chọn nguồn. Gói Miễn phí dùng **File Excel**: bấm **Tải file lên** và chọn file `.xlsx` (tối đa 50 MB). Xem cách chuẩn bị file ở [File Excel](/vi/docs/sources/excel). 4. Bấm **Tạo workspace và đọc dữ liệu**. ## 4. Chọn cột cần che (2 phút) Bước **Chọn dữ liệu và thông tin cá nhân** liệt kê cột nghi chứa thông tin cá nhân. Giữ dấu che cho tên, số điện thoại, email, địa chỉ; đánh dấu đồng ý gửi mẫu đã che rồi bấm **Xác nhận và để Si phân tích**. Chi tiết: [Che thông tin cá nhân](/vi/docs/review/pii). ## 5. Làm rõ và duyệt (10–20 phút) Si đọc mẫu đã che và soạn đề xuất, thường mất 1–3 phút. Sau đó: 1. Bước **Làm rõ và xem lại**: đọc **Si hiểu dữ liệu của bạn**, chọn đáp án ở mục **Si cần bạn chọn** (lựa chọn Si đề xuất đã chọn sẵn), bấm **Lưu và tiếp tục**. Xem [Trả lời câu hỏi của Si](/vi/docs/review/questions). 2. Bước **Duyệt và build**: xem **Si sẽ dựng** (chỉ số kèm cách tính, trang dashboard), **Câu trả lời của bạn** và **Giả định**, rồi bấm **Duyệt và build**. Không có gì được build khi workspace chưa được duyệt. ## 6. Đọc dashboard Build chạy nền: nạp dữ liệu, biến đổi, kiểm tra chất lượng rồi công bố. Khi trạng thái là **Sẵn sàng**, bấm **Mở dashboard**. Đổi kỳ bằng bộ chọn ngày (mặc định **90 ngày qua**), thêm bộ lọc bằng **Thêm bộ lọc**. Bấm **Vì sao?** trên một ô số để xem nguyên nhân thay đổi. ## 7. Hỏi Si Mở **Hỏi Si** ở thanh bên, gõ câu hỏi, ví dụ "Tháng gần nhất doanh thu và lãi thế nào?", rồi bấm **Hỏi**. Mỗi câu trả lời có phần **Nguồn** và mức xác nhận. Xem [Hỏi Si trong ứng dụng](/vi/docs/ask/app). ## Liên quan - [Kết nối dữ liệu](/vi/docs/connect-data) - [Duyệt đề xuất và build](/vi/docs/review/mapping) - [Gói và hạn mức](/vi/docs/billing/quotas) --- # Bảo mật và quyền riêng tư > Che và băm thông tin cá nhân, kho tách theo workspace, mã hóa bí mật, vai trò và 2FA, sao lưu mã hóa, mục tiêu OWASP ASVS cấp 1, xuất và xóa dữ liệu. Tóm tắt kỹ thuật; điều khoản ràng buộc ở [Chính sách riêng tư](/vi/privacy), [Thỏa thuận xử lý dữ liệu](/vi/dpa) và [Bảo mật](/vi/security). ## Thông tin cá nhân - Cột được đánh dấu là thông tin cá nhân bị **che trước khi vào prompt** của Si. - Giá trị được **băm** (SHA-256 với salt riêng của workspace) ngay khi nạp; kho đã công bố không chứa salt. Lưu giá trị gốc là lựa chọn bạn chủ động bật, mặc định tắt. - Không API, Si hay MCP nào trả thông tin cá nhân người mua. - Si chỉ đọc mẫu tối đa 1.000 dòng đã che, và chỉ khi bạn đồng ý. Xem [Che thông tin cá nhân](/vi/docs/review/pii). ## Tách dữ liệu theo workspace - Mỗi workspace có kho riêng: file Parquet dưới một vùng lưu trữ riêng, danh mục bảng riêng và **khóa lưu trữ riêng** chỉ đọc được vùng của workspace đó. - Dashboard, Si và MCP chỉ đọc bản đã công bố của đúng workspace; mọi yêu cầu được kiểm tra người gọi có quyền với workspace. ## Bí mật và mật khẩu - Mật khẩu nguồn, khóa service account, token Slack và bí mật 2FA được **mã hóa khi lưu** và không hiển thị lại; khóa mã hóa xoay vòng được. - Mật khẩu đăng nhập được băm bằng Argon2id. - Token MCP chỉ lưu dạng băm, có hạn, thu hồi được. ## Truy cập - Bốn vai trò cho từng workspace: Chủ sở hữu, Quản trị, Phân tích, Xem. Xem [Thành viên và vai trò](/vi/docs/workspace/members). - Xác thực hai lớp bằng ứng dụng tạo mã, 10 mã khôi phục; Chủ sở hữu có thể **bắt buộc 2FA** cho Chủ sở hữu và Quản trị. - Phiên ngắn (mã truy cập 15 phút), đăng xuất từng thiết bị hoặc mọi thiết bị; tạm khóa đăng nhập 15 phút sau 5 lần sai. - Nhật ký bảo mật cho từng workspace; mỗi lời gọi công cụ của Si và MCP được ghi lại. ## Ứng dụng web - Header bảo mật: Content Security Policy theo từng yêu cầu, chặn nhúng khung, HSTS trên bản chính thức. - Giới hạn tốc độ cho đăng nhập, hỏi Si và MCP. - Mục tiêu kiểm soát theo **OWASP ASVS 4.0.3 cấp 1**; danh sách kiểm được theo dõi nội bộ, một số mục (như cấu hình TLS của bản chính thức) đang hoàn thiện. Đây là mục tiêu, không phải chứng nhận. ## Sao lưu - Sao lưu tự động hằng ngày, giữ 7 bản ngày, 4 bản tuần, 6 bản tháng. - Bản sao lưu được **mã hóa trước khi gửi đi** (AES-256-GCM) bằng khóa riêng, rồi lưu trên object storage có mã hóa, lưu phiên bản và khóa chống xóa. - Mục tiêu: mất tối đa 24 giờ dữ liệu, khôi phục trong 4 giờ. ## Xuất và xóa Bạn xuất toàn bộ dữ liệu của workspace, tải dữ liệu cá nhân, xóa workspace (7 ngày khôi phục) hoặc xóa tài khoản bất kỳ lúc nào. Xem [Xuất và xóa dữ liệu](/vi/docs/workspace/export-delete). ## Báo lỗ hổng Gửi tới security@dataxland.com. ## Liên quan - [Kiến trúc](/vi/docs/architecture) - [Xác thực hai lớp](/vi/docs/workspace/2fa) - [Trang Bảo mật](/vi/security) --- # Si: phân tích ngữ cảnh và hỏi đáp > Si là trợ lý dữ liệu AI của DataxLand — đề xuất cách hiểu và ánh xạ dữ liệu cho bạn duyệt, và trả lời câu hỏi bằng chỉ số đã duyệt. **Si** là một trợ lý làm hai việc: **Si phân tích ngữ cảnh** (đọc dữ liệu, đề xuất ánh xạ để người duyệt) và **Si hỏi đáp** (trả lời trong ứng dụng, qua Slack, Microsoft Teams, Telegram và MCP). Trong ứng dụng, mọi chỗ đều gọi là Si: phần phân tích ngữ cảnh (ví dụ nút **Nhờ Si đề xuất**), màn hỏi đáp **Hỏi Si** và khung **Hỏi Si** bên phải dashboard. Khi cần phân biệt (trang quản trị, chi phí), hai phần được ghi là **Si · Phân tích ngữ cảnh** và **Si · Hỏi đáp**. Tên cũ Copilot, "Hỏi AI", AI Agent không còn trên màn hình. ## Si phân tích ngữ cảnh Khi bạn kết nối nguồn, Si đọc cấu trúc bảng, mô tả cột và một mẫu dữ liệu **đã che thông tin cá nhân** (tối đa 1.000 dòng, chỉ khi bạn đồng ý), rồi đi qua các bước bạn thấy trong khung **Si đang phân tích…**: 1. Đọc cấu trúc bảng và mẫu dữ liệu đã che 2. Điều tra dữ liệu 3. Chọn mẫu phân tích phù hợp 4. Hiểu mô hình kinh doanh 5. Ánh xạ cột vào mô hình chuẩn 6. Chuẩn hóa giá trị: trạng thái, kênh, loại phí 7. Chọn chỉ số dùng được 8. Soạn câu hỏi cần bạn xác nhận 9. Đề xuất bố cục menu và Trang chính 10. Lưu đề xuất Khi điều tra, Si được chạy truy vấn **chỉ đọc** trên mẫu đã che hoặc trên database nguồn, trong giới hạn số câu và chi phí; câu vượt giới hạn chờ người kỹ thuật xác nhận. Mô hình dữ liệu cuối cùng do DataxLand sinh từ kế hoạch bạn duyệt; truy vấn Si viết không bao giờ được đưa vào build. Bạn giúp Si hiểu đúng hơn bằng sheet `data_dictionary`, ô **Bối cảnh dữ liệu cho Si** (ghi chú, tài liệu mô tả) và trang [Kiến thức](/vi/docs/metrics/knowledge). ## Si đề xuất, người duyệt Bản ánh xạ, chỉ số mới của workspace và mô hình ngữ nghĩa đều là **bản nháp** cho tới khi Quản trị hoặc Chủ sở hữu duyệt. Không có gì được build khi workspace chưa ở trạng thái **Đã duyệt**. Ô Si ghim vào trang hiện nhãn **Nháp** cho tới khi bạn bấm **Lưu**. Xem [Duyệt đề xuất và build](/vi/docs/review/mapping). ## Si hỏi đáp Si trả lời câu hỏi trong [ứng dụng](/vi/docs/ask/app), trong [Slack](/vi/docs/channels/slack), [Microsoft Teams](/vi/docs/channels/teams) và [Telegram](/vi/docs/channels/telegram), và qua [MCP](/vi/docs/mcp). Si **chỉ đọc chỉ số qua lớp ngữ nghĩa**: câu hỏi được dịch thành chỉ số, chiều, bộ lọc, kỳ và so sánh; máy của DataxLand dựng truy vấn từ định nghĩa đã duyệt. Con số Chuẩn và Đã duyệt không bao giờ đến từ SQL do model viết; câu hỏi khám phá vượt ra ngoài chỉ số có sẵn thì Si viết SQL/Python chạy trong sandbox cách ly, kết quả luôn gắn nhãn Chưa xác nhận (xem [Si viết và chạy SQL/Python](/vi/docs/ask/sandbox)). ### Mức xác nhận | Mức | Nghĩa | | --- | --- | | Chuẩn | Chỉ số chuẩn của gói ngành × phòng ban | | Đã duyệt | Chỉ số riêng của workspace, đã kiểm số và được duyệt | | Chưa xác nhận | Câu trả lời khám phá trên mô hình đã duyệt; kiểm tra trước khi dùng như số chính thức | Xem [Chỉ số và lớp ngữ nghĩa](/vi/docs/metrics). ## Dữ liệu cá nhân Cột thông tin cá nhân bị che trước khi vào prompt và bị băm trong kho. Si không trả thông tin cá nhân của người mua. Xem [Bảo mật và quyền riêng tư](/vi/docs/security-privacy). ## Liên quan - [Trả lời câu hỏi của Si](/vi/docs/review/questions) - [Trình giải thích con số](/vi/docs/ask/inspector) - [Si trên trang tính năng](/vi/platform/si) --- # API HTTP — tổng quan > Quy ước của API HTTP DataxLand — xác thực Bearer, chọn workspace, dạng lỗi, giới hạn tốc độ (429, Retry-After), hạn mức (402) và nhóm tài nguyên. API HTTP của DataxLand là API mà ứng dụng web dùng; mọi thao tác trong ứng dụng đều đi qua nó. Hiện **chưa có khóa API riêng** cho tích hợp máy với máy: để AI agent hay công cụ bên ngoài đọc chỉ số, dùng [máy chủ MCP](/vi/docs/mcp) với token có hạn và thu hồi được. ## Địa chỉ và phiên bản - Mọi đường dẫn bắt đầu bằng `/v1`. Từ trình duyệt, ứng dụng gọi qua `/api/v1/…` trên cùng domain của ứng dụng. - Phản hồi là JSON UTF-8. Ngày dạng `YYYY-MM-DD`; thời điểm ISO 8601 theo UTC. Ngày nghiệp vụ (kỳ, "dữ liệu đến") theo múi giờ của workspace. - Trên giao diện gọi là **workspace**, trong API là `tenant`. ## Xác thực 1. `POST /v1/auth/login` trả mã truy cập (JWT) sống 15 phút. 2. Gửi kèm mỗi yêu cầu: `Authorization: Bearer `. 3. Làm mới bằng `POST /v1/auth/refresh`, dùng cookie phiên `dx_refresh` (HttpOnly) và header `X-DX-CSRF: 1`. Thiếu, sai hoặc hết hạn mã: `401`. Thiếu vai trò ở workspace: `403`. Tài khoản bật 2FA phải nhập mã khi đăng nhập. ## Chọn workspace - Đường dẫn `/v1/tenants/{id}/…` dùng `{id}`. - Các endpoint chỉ số, dashboard và hỏi đáp (`/v1/metrics…`, `/v1/dashboards…`, `/v1/ask`) dùng header `X-DX-Tenant: `. Workspace không thuộc người dùng: `403`. ## Lỗi Mọi lỗi có cùng dạng: ```json { "detail": { "code": "quota_exceeded", "message": "Gói … cho tối đa …", "details": null } } ``` | Mã HTTP | Khi nào | | --- | --- | | 400 | Sai tham số; file Excel không hợp lệ | | 401 | Chưa đăng nhập hoặc mã hết hạn | | 402 | Hết hạn mức của gói, `code = quota_exceeded` | | 403 | Không có quyền, hoặc thiếu header CSRF | | 404 | Không tìm thấy | | 409 | Xung đột trạng thái, ví dụ workspace đang có lần chạy | | 413 | `too_large`: thân yêu cầu quá lớn (multipart trên 110 MB, JSON trên 5 MB) | | 422 | Bản duyệt không hợp lệ; `details` là danh sách lỗi | | 429 | `rate_limited`: vượt giới hạn tốc độ | `message` viết bằng tiếng Việt, hiển thị được cho người dùng. ## Giới hạn tốc độ (429) Vượt giới hạn trả `429` với `code = "rate_limited"`, header **`Retry-After`** (giây) và `details.retry_after`. Chờ đúng số giây đó rồi thử lại; đừng thử lại liên tục. | Nhóm | Giới hạn | | --- | --- | | Đăng nhập | 20 mỗi phút mỗi IP | | Đăng ký | 10 mỗi 10 phút mỗi IP | | Hỏi Si (`POST /ask`, tin trong phiên) | 20 mỗi phút mỗi người, 60 mỗi phút mỗi workspace | | Tải file | 30 mỗi 10 phút mỗi người | | MCP | 60 mỗi phút mỗi token, 120 mỗi phút mỗi người | ## Hạn mức (402) Thao tác tạo thêm vượt hạn mức gói trả `402 quota_exceeded`; thao tác xem không bao giờ bị chặn. Xem [Gói và hạn mức](/vi/docs/billing/quotas). ## Nhóm tài nguyên | Nhóm | Ví dụ | | --- | --- | | Đăng nhập, tài khoản, thành viên | phiên, 2FA, lời mời, vai trò | | Workspace | tạo, trạng thái, duyệt, build, cài đặt | | Nguồn dữ liệu | nguồn, connector, OAuth sàn, lịch làm mới, xác nhận thông tin cá nhân | | Chỉ số và dashboard | sổ tay chỉ số, truy vấn chỉ số, trang dashboard | | Lớp ngữ nghĩa | mô hình ngữ nghĩa, truy vấn ngữ nghĩa, "vì sao", chỉ số và trang của workspace | | Hỏi đáp | hỏi Si, lịch sử, kiến thức | | Thông báo | đích nhận, báo cáo định kỳ, cảnh báo, hỏi đáp qua chat | | Tích hợp | token MCP | | Gói | mức dùng, mua thêm | | Quyền với dữ liệu | xuất workspace, xuất dữ liệu cá nhân, xóa | Tài liệu tương tác của API (`/docs`) tắt trên bản chính thức. ## Liên quan - [Máy chủ MCP](/vi/docs/mcp) - [Bảo mật và quyền riêng tư](/vi/docs/security-privacy) - [Gói và hạn mức](/vi/docs/billing/quotas) --- # Hỏi Si trong ứng dụng > Hỏi Si bằng tiếng Việt ở màn Hỏi Si hoặc khung Hỏi Si trên dashboard; đọc phần Nguồn và mức xác nhận, sửa cách hiểu câu hỏi, bật Suy nghĩ sâu. Màn **Hỏi Si** (nhóm **Hỏi và tra cứu**) là nơi hỏi Si. Si chỉ dùng chỉ số trong [Sổ tay chỉ số](/vi/docs/metrics); mỗi câu trả lời có phần **Nguồn**. Cần vai trò Phân tích trở lên. ## Đặt câu hỏi 1. Gõ câu hỏi vào ô (ví dụ "Hỏi về doanh thu, lãi, chi phí…") hoặc bấm một mục ở **Gợi ý câu hỏi**. 2. Bấm **Hỏi**. Câu hỏi tốt nói rõ chỉ số, kỳ và cách tách: | Thay vì | Hỏi | | --- | --- | | "Bán thế nào?" | "Doanh thu thuần tháng trước theo kênh" | | "Lãi?" | "Lãi sau phí 28 ngày qua so với kỳ trước" | | "Sản phẩm nào tốt?" | "Top 10 sản phẩm theo lãi gộp tháng này" | ## Đọc câu trả lời - **Nguồn**: chỉ số và phiên bản đã dùng, kỳ, "dữ liệu đến" ngày nào. - **Mức xác nhận**: **Chuẩn**, **Đã duyệt** hoặc **Chưa xác nhận** (xem [Chỉ số và lớp ngữ nghĩa](/vi/docs/metrics)). - **Công cụ đã gọi**: các bước tra cứu Si đã làm. **Xem phân tích vì sao** mở phần giải thích. - Si nói **Không trả lời được câu này** khi chỉ số không có hoặc dữ liệu không đủ, thay vì đoán. ## Ngôn ngữ trả lời Si trả lời bằng ngôn ngữ bạn hỏi: hỏi tiếng Việt (có dấu hay không dấu) thì trả lời tiếng Việt; hỏi tiếng Anh thì trả lời tiếng Anh, dòng nguồn ghi **Source**. Câu quá ngắn để nhận ra ngôn ngữ (ví dụ "GMV?") thì Si theo ngôn ngữ của câu hỏi trước trong cuộc trò chuyện, rồi theo thiết lập **Định dạng số và ngày** của workspace ([múi giờ, tiền tệ và định dạng](/vi/docs/workspace/region)). Muốn đổi, chỉ cần nói "trả lời bằng tiếng Anh". Số và tiền luôn theo định dạng của workspace để khớp dashboard. ## Sửa cách hiểu câu hỏi Dưới câu trả lời, **Cách hiểu câu hỏi** liệt kê các thẻ Chỉ số, Chiều, Bộ lọc, Kỳ, So sánh, Top. Bấm một thẻ để sửa rồi **Chạy lại**. Lần chạy lại đi thẳng vào lớp ngữ nghĩa, không hỏi lại AI. Từ thẻ kết quả bạn **Ghim vào trang** được. ## Suy nghĩ sâu Bật **Suy nghĩ sâu** cho câu hỏi cần phân tích nhiều bước ("vì sao lãi tháng này giảm, do kênh nào, sản phẩm nào"). Chậm hơn, có thể mất khoảng một phút; mục **Quá trình suy nghĩ** cho xem lập luận. Không có ở gói Miễn phí. ## Hỏi về một trang dashboard Trên dashboard, bấm **Hỏi Si** ở thanh trên. Si biết bạn đang xem trang nào ("Đang hỏi về: …") và gợi ý "Tóm tắt trang này", "Có điều gì bất thường?". ## Lịch sử và kiến thức **Lịch sử** giữ các cuộc hỏi đáp; **Cuộc hỏi đáp mới** để bắt đầu lại. Dưới câu trả lời đúng, bấm **Đánh dấu đúng** hoặc **Lưu vào kiến thức** để Si dùng lại (xem [Kiến thức](/vi/docs/metrics/knowledge)). ## Hạn mức Mỗi câu hỏi tính vào hạn mức câu hỏi cho Si của gói mỗi tháng (Miễn phí 30, Khởi đầu 300, Doanh nghiệp nhỏ 1.500). Hết hạn mức thì tạm dừng hỏi; dashboard và báo cáo vẫn chạy. Xem [Gói và hạn mức](/vi/docs/billing/quotas). ## Liên quan - [Trình giải thích con số](/vi/docs/ask/inspector) - [Hỏi Si trong Slack](/vi/docs/channels/slack) · [Telegram](/vi/docs/channels/telegram) - [Máy chủ MCP](/vi/docs/mcp) --- # Trình giải thích con số > Mở trình giải thích của một ô hay một điểm trên biểu đồ để xem tóm tắt, dữ kiện, phân tách, vì sao thay đổi so với kỳ trước và câu SQL đã chạy. Mỗi con số trên dashboard mở được để xem nó đến từ đâu. Phần giải thích do máy tính chỉ số tính từ định nghĩa, không do AI viết. ## Mở trình giải thích - Bấm **Chi tiết** trên một ô, hoặc bấm vào một cột, một điểm của biểu đồ. - Bấm **Vì sao?** trên ô số để mở thẳng thẻ **Vì sao thay đổi**. ## Các thẻ | Thẻ | Cho thấy | | --- | --- | | Tóm tắt | Giá trị, kỳ, bộ lọc đang áp, so với kỳ trước | | Facts | Dữ kiện chính của điểm đang chọn | | Phân tách | Con số tách theo một chiều (kênh, sản phẩm…) | | Vì sao thay đổi | Đóng góp của từng phần vào thay đổi | | SQL | Câu truy vấn máy tính chỉ số đã chạy (**Sao chép** được) | ## Vì sao thay đổi Chọn **So với kỳ trước** (vì sao tăng, giảm) hoặc **Vì sao ở mức này**. Trang giải thích theo nhiều cách: - **Theo công thức**: chỉ số tách thành các thành phần (ví dụ lãi sau phí = doanh thu thuần − giá vốn − phí), thành phần nào kéo thay đổi; - **Theo cây công thức**: cùng cách đó, nhiều tầng; - **Kéo xuống nhiều nhất** / **Đẩy lên nhiều nhất**: giá trị của một chiều (kênh, sản phẩm) đóng góp lớn nhất; - **Tổ hợp hai chiều nổi bật**: ví dụ một sản phẩm trên một kênh; - bảng **Kỳ này**, **Kỳ so sánh**, **Thay đổi**. ## Hỏi tiếp, ghim - **Hỏi Si về điểm này**: mở khung Hỏi Si với điểm đang chọn làm ngữ cảnh. - **Ghim vào trang**: xem [Dashboard và ghim vào trang](/vi/docs/dashboards/pin). - **Bỏ chọn** để đóng. Si cũng dùng cùng phần giải thích khi bạn hỏi "vì sao", trong ứng dụng, Slack, Telegram hay qua MCP. ## Liên quan - [Hỏi Si trong ứng dụng](/vi/docs/ask/app) - [Chỉ số và lớp ngữ nghĩa](/vi/docs/metrics) - [Số có kiểm tra](/vi/docs/data-quality) --- # Si viết và chạy SQL/Python > Với câu hỏi khám phá vượt quá chỉ số có sẵn (trung vị, phân vị, tương quan, nối hai bảng, biểu đồ tùy ý), Si tự viết SQL hoặc Python và chạy trong sandbox cách ly. Kết quả luôn ở mức Chưa xác nhận. Phần lớn câu hỏi được Si trả lời bằng **chỉ số** và **lớp ngữ nghĩa** — số **Chuẩn** hoặc **Đã duyệt**, khớp với dashboard. Khi câu hỏi vượt quá chỉ số có sẵn, Si có thể **tự viết SQL hoặc Python** và chạy trong **sandbox khám phá**. Đây là công cụ cho người phân tích, không thay chỉ số chính thức. ## Khi nào Si dùng sandbox | Câu hỏi | Si dùng | | --- | --- | | Doanh thu, lãi, số đơn, tỷ lệ hoàn; so kỳ trước; top N; "vì sao giảm" | Chỉ số và lớp ngữ nghĩa (số Chuẩn) | | Trung vị, phân vị, phân phối giá trị đơn | Sandbox (SQL) | | Tương quan chi phí quảng cáo và doanh thu theo ngày | Sandbox (SQL hoặc Python) | | Nối hai bảng theo khóa chưa có sẵn trong mô hình | Sandbox (SQL) | | Cohort theo tháng, hồi quy đơn giản, biểu đồ tùy ý | Sandbox (Python) | Si luôn thử lớp ngữ nghĩa trước. Nó không dùng sandbox để tính lại một chỉ số đã có. ## Mức xác nhận: luôn "Chưa xác nhận" Mọi số tính trong sandbox mang nhãn **Chưa xác nhận**: code do Si viết, chưa ai kiểm định nghĩa. Câu trả lời ghi rõ dòng **Mức xác nhận** và dưới câu trả lời có thẻ cho từng lần chạy: - nhãn **Chưa xác nhận**; - **Xem code SQL / Python** (gập sẵn) — đọc để biết Si tính thế nào; - bảng kết quả (tối đa 100 dòng), biểu đồ (tối đa 2), nội dung in ra. Kết quả sandbox **không** ghim được thành ô dashboard và **không** lưu được thành "Câu trả lời đã xác nhận". Muốn dùng lâu dài: 1. **Lưu bản nháp vào kiến thức** (kèm code) để người duyệt đọc; hoặc 2. nhờ Si **lưu thành chỉ số** — Si tạo chỉ số nháp trên mô hình ngữ nghĩa, người duyệt kiểm số rồi bật (xem [Chỉ số của workspace](/vi/docs/metrics/workspace-metrics)). ## Sandbox được đọc gì - Chỉ dữ liệu **đã publish** (cùng bản dashboard đang hiện), lớp **core** và **marts**. Không có dữ liệu thô (`raw`) hay lớp trung gian. - **Không có thông tin cá nhân**: cột như số điện thoại, email, tên người mua, cột đã băm và mã định danh khách bị loại trước khi dữ liệu vào sandbox. Muốn đếm số khách, Si dùng lớp ngữ nghĩa. - Bản sao chỉ đọc: code không ghi được vào dữ liệu, chỉ số hay cấu hình của workspace. ## An toàn - Code chạy trong **dịch vụ sandbox riêng**, không có mạng, không đọc được file ngoài thư mục tạm của lần chạy, không có khóa hay mật khẩu nào. Mỗi lần chạy có giới hạn: 30 giây, bộ nhớ, 200 dòng kết quả cho Si. - SQL chỉ được là **một câu đọc** (SELECT); câu ghi, đọc file, đổi cấu hình bị từ chối trước khi chạy. - Mỗi lần chạy được ghi nhật ký kiểm toán: **code** và **số dòng** kết quả (không ghi giá trị dữ liệu). ## Ai dùng được - Vai trò **Phân tích**, **Quản trị**, **Chủ sở hữu**. Vai trò **Xem** không có. - Gói **Doanh nghiệp nhỏ** trở lên (xem [Gói và hạn mức](/vi/docs/billing/quotas)). Mỗi lần chạy tính thêm **1 câu hỏi cho Si**. - Tối đa 4 lần chạy cho một câu hỏi, 20 lần mỗi phút mỗi người. - Chỉ trong ứng dụng web. Hỏi qua Telegram, Slack, Teams không dùng sandbox. - Qua MCP: chỉ token được cấp thêm quyền `explore:run` (mặc định không có), xem [MCP](/vi/docs/mcp). ## Câu hỏi thường gặp **Vì sao số trong sandbox khác dashboard?** Code của Si có thể lọc hay gom khác định nghĩa chỉ số (ví dụ tính cả đơn hủy). Mở "Xem code" để thấy cách tính; số chính thức vẫn là số trên dashboard. **Si báo "Sandbox khám phá chưa bật"?** Máy chủ của bạn chưa chạy dịch vụ sandbox; liên hệ quản trị (bản tự triển khai). **Si báo hết lượt?** Mỗi lần chạy tính vào câu hỏi cho Si trong tháng; mua thêm gói 500 câu hỏi hoặc nâng gói. --- # Hỏi Si trong Slack > Cài DataxLand vào Slack, nối tài khoản bằng mã dùng một lần với /dataxland link, hỏi Si trong tin nhắn riêng hoặc kênh, gắn kênh với workspace. Si trả lời trong Slack đúng như trong ứng dụng: số, nguyên nhân, mức xác nhận và link **Mở trong DataxLand**. Có ở mọi gói; mỗi câu hỏi tính vào hạn mức câu hỏi cho Si của workspace. Người hỏi cần vai trò Phân tích trở lên. ## 1. Cài app và nối tài khoản 1. Mở **Tài khoản**, thẻ **Kết nối chat**, bấm **Nối Slack**. 2. Nếu Slack workspace của bạn chưa có DataxLand, bấm **Cài DataxLand vào Slack** và cho phép trên trang Slack (một lần cho mỗi Slack workspace). 3. Bấm **Tạo mã nối**. Mã dùng một lần, hết hạn sau 10 phút. 4. Trong Slack, gõ `/dataxland link lk_`. DataxLand trả lời "Đã nối…" là xong. Gỡ nối ở **Kết nối chat → Gỡ nối** hoặc gõ `/dataxland unlink`. ## 2. Hỏi - **Tin nhắn riêng** cho DataxLand: nhắn câu hỏi bình thường. - **Trong kênh**: nhắc `@DataxLand` kèm câu hỏi, hoặc gõ `/dataxland ask `. Kênh cần được gắn với một workspace: người có vai trò Quản trị trở lên gõ `/dataxland ws ` trong kênh đó. Quản trị gỡ gắn ở **Cài đặt → Thông báo → Chat hỏi đáp**. ## Lệnh Slack dùng cùng lệnh với Telegram, không có dấu `/` ở đầu, sau `/dataxland` (hoặc trong tin nhắn riêng): | Lệnh | Việc | | --- | --- | | `ask ` | Hỏi số liệu | | `think ` | Hỏi với Suy nghĩ sâu (tính 3 câu hỏi) | | `new` | Bắt đầu cuộc hỏi đáp mới | | `ws` | Xem hoặc đổi workspace | | `link`, `unlink` | Nối, gỡ nối tài khoản | | `help` | Cách dùng | ## Hai app Slack khác nhau - **DataxLand** (cài bằng **Cài DataxLand vào Slack**): để **hỏi Si**, trang này. - **App báo cáo** bạn tự tạo từ manifest ở **Cài đặt → Thông báo**: để **nhận báo cáo và cảnh báo** vào một kênh, xem [Báo cáo và cảnh báo](/vi/docs/alerts-reports). Hai app độc lập; dùng một hay cả hai đều được. ## Giới hạn - Câu trả lời dài được cắt ở khoảng 2.900 ký tự kèm link mở đầy đủ trong DataxLand. - Hỏi quá nhanh thì nhận "Bạn hỏi quá nhanh; chờ ít giây rồi hỏi tiếp.". - Si không trả thông tin cá nhân người mua trong chat. ## Liên quan - [Hỏi Si trong Telegram](/vi/docs/channels/telegram) - [Hỏi Si trong ứng dụng](/vi/docs/ask/app) - [Thành viên và vai trò](/vi/docs/workspace/members) --- # Microsoft Teams > Thêm ứng dụng DataxLand vào Microsoft Teams để nhận báo cáo, cảnh báo kèm biểu đồ và hỏi Si ngay trong kênh hoặc chat riêng; nối tài khoản bằng mã dùng một lần. DataxLand trong Microsoft Teams làm được hai việc, cùng một ứng dụng: - **Nhận báo cáo định kỳ và cảnh báo** vào một kênh, nhóm chat hoặc chat riêng, kèm biểu đồ. - **Hỏi Si** số liệu: câu trả lời giống trong ứng dụng (số, nguyên nhân, mức xác nhận, nút **Mở trong DataxLand**), tính vào hạn mức câu hỏi cho Si của workspace. Người hỏi cần vai trò Phân tích trở lên. Teams có ở mọi gói đang có Slack. ## 1. Thêm ứng dụng DataxLand vào Teams rồi hỏi tiếp trong thread." /> Trong Teams mở **Ứng dụng**, tìm **DataxLand** và bấm **Thêm**. Nếu công ty bạn chặn ứng dụng bên ngoài, nhờ quản trị Teams cho phép DataxLand (Trung tâm quản trị Teams → Ứng dụng). Muốn dùng trong một kênh: mở kênh → **+** (Thêm ứng dụng) → DataxLand. Trang **Kết nối chat** và hộp thoại tạo đích có nút **Thêm DataxLand vào Teams** khi máy chủ đã có link cài ứng dụng. ## 2. Nối tài khoản để hỏi Si 1. Mở **Tài khoản**, thẻ **Kết nối chat**, bấm **Nối Microsoft Teams**. 2. Bấm **Tạo mã nối**. Mã dùng một lần, hết hạn sau 10 phút. 3. Mở **chat riêng** với DataxLand trong Teams và gửi `link lk_`. DataxLand trả lời "Đã nối…" là xong. Vì an toàn, mã gửi trong kênh hoặc nhóm bị từ chối (người khác thấy được) và không bị tiêu. Gỡ nối ở **Kết nối chat → Gỡ nối** hoặc gửi `unlink`. ## 3. Hỏi - **Chat riêng** với DataxLand: nhắn câu hỏi bình thường. - **Trong kênh hoặc nhóm**: nhắc `@DataxLand` kèm câu hỏi. Teams chỉ gửi cho DataxLand những tin có nhắc tên, DataxLand không đọc các tin khác. Câu trả lời nằm trong thread của câu hỏi; mọi người trong kênh đều thấy. Kênh cần được gắn với một workspace: người có vai trò Quản trị trở lên gửi `@DataxLand ws ` trong kênh đó. Kênh đã nối làm đích báo cáo (mục 4) được gắn tự động. Quản trị gỡ gắn ở **Cài đặt → Thông báo → Chat hỏi đáp**. ## 4. Nhận báo cáo và cảnh báo vào Teams 1. Vào **Cài đặt → Thông báo**, bấm **Thêm Microsoft Teams**, đặt tên đích (ví dụ "Kênh Bán hàng") rồi **Nối Microsoft Teams**. 2. Trong kênh, nhóm hoặc chat riêng đã có DataxLand, gửi `@DataxLand connect nd_` (mã hết hạn sau 15 phút). 3. Trang tự chuyển sang **Đang hoạt động**. Bấm **Gửi thử** để kiểm tra. Rồi chọn đích này khi tạo [báo cáo định kỳ hoặc cảnh báo](/vi/docs/alerts-reports). Mỗi tin là một thẻ có tiêu đề, số liệu và nút mở dashboard; biểu đồ gửi ngay sau thẻ. ## Lệnh Gõ không có dấu `/` ở đầu, trong chat riêng hoặc sau `@DataxLand`: | Lệnh | Việc | | --- | --- | | `` | Hỏi số liệu | | `think ` | Hỏi với Suy nghĩ sâu (tính 3 câu hỏi) | | `new` | Bắt đầu cuộc hỏi đáp mới | | `ws` | Xem hoặc đổi workspace (trong kênh: gắn kênh với workspace) | | `link`, `unlink` | Nối, gỡ nối tài khoản | | `connect ` | Nhận báo cáo, cảnh báo vào cuộc trò chuyện này | | `help` | Cách dùng | ## Giới hạn - Câu trả lời dài được cắt ở khoảng 6.000 ký tự kèm nút mở đầy đủ trong DataxLand. - Biểu đồ lớn hơn 1 MB không gửi được (biểu đồ của DataxLand thường chỉ vài chục KB). - DataxLand không gửi được tin vào kênh riêng tư (private channel) của Teams; dùng kênh thường, nhóm chat hoặc chat riêng. - Hỏi quá nhanh thì nhận "Bạn hỏi quá nhanh; chờ ít giây rồi hỏi tiếp.". - Si không trả thông tin cá nhân người mua trong chat. ## Liên quan - [Hỏi Si trong Slack](/vi/docs/channels/slack) - [Hỏi Si trong Telegram](/vi/docs/channels/telegram) - [Báo cáo và cảnh báo](/vi/docs/alerts-reports) - [Thành viên và vai trò](/vi/docs/workspace/members) --- # Hỏi Si trong Telegram > Nối tài khoản DataxLand với Telegram bằng mã dùng một lần, hỏi Si trong chat riêng hoặc nhóm, gắn nhóm với workspace và các lệnh /ask, /think, /ws. Si trả lời trong Telegram đúng như trong ứng dụng: số, nguyên nhân, mức xác nhận và link **Mở trong DataxLand**. Có ở mọi gói; mỗi câu hỏi tính vào hạn mức câu hỏi cho Si của workspace. Người hỏi cần vai trò Phân tích trở lên. ## 1. Nối tài khoản (một lần) 1. Mở **Tài khoản** (menu người dùng), thẻ **Kết nối chat**, bấm **Nối Telegram**. 2. Ở trang **Nối chat với tài khoản**, bấm **Tạo mã nối**. Mã dùng một lần, hết hạn sau 10 phút. 3. Bấm **Mở Telegram** rồi bấm **Start** với bot DataxLand. Hoặc gửi cho bot tin `/start lk_`. 4. Bot trả lời "Đã nối…" là xong. Mã chỉ nhận trong chat riêng với bot: gửi mã vào nhóm thì bị từ chối (và mã vẫn dùng được). Gỡ nối ở **Kết nối chat → Gỡ nối** hoặc gửi `/unlink`. ## 2. Hỏi trong chat riêng Nhắn câu hỏi bình thường cho bot: "Doanh thu hôm qua theo kênh?". Nếu bạn ở nhiều workspace, gửi `/ws` để xem hoặc đổi workspace đang hỏi. ## 3. Dùng trong nhóm 1. Thêm bot DataxLand vào nhóm. 2. Một người có vai trò Quản trị trở lên gửi `/ws ` để gắn nhóm với workspace. Nhóm đã nối làm đích nhận thông báo thì được gắn sẵn. 3. Thành viên đã nối tài khoản hỏi bằng `/ask `, nhắc tên bot, hoặc trả lời vào tin của bot. Trong nhóm, bot chỉ đọc `/ask`, tin nhắc tên bot và tin trả lời vào tin của bot; không đọc tin trò chuyện khác. Quản trị gỡ gắn nhóm ở **Cài đặt → Thông báo → Chat hỏi đáp**. ## Lệnh | Lệnh | Việc | | --- | --- | | `/ask ` | Hỏi số liệu (cần trong nhóm) | | `/think ` | Hỏi với Suy nghĩ sâu (tính 3 câu hỏi) | | `/new` | Bắt đầu cuộc hỏi đáp mới | | `/ws` | Xem hoặc đổi workspace | | `/link` | Nối tài khoản DataxLand | | `/unlink` | Gỡ nối tài khoản | | `/help` | Cách dùng | Cuộc hỏi đáp mới bắt đầu sau 30 phút im lặng hoặc khi gửi `/new`. ## Giới hạn - Câu trả lời dài được cắt ở khoảng 3.500 ký tự kèm link mở đầy đủ trong DataxLand. - Hỏi quá nhanh thì bot trả lời "Bạn hỏi quá nhanh; chờ ít giây rồi hỏi tiếp." (20 câu mỗi phút mỗi người, 60 câu mỗi phút mỗi workspace). - Si không trả thông tin cá nhân người mua trong chat. ## Liên quan - [Hỏi Si trong Slack](/vi/docs/channels/slack) - [Báo cáo và cảnh báo](/vi/docs/alerts-reports) - [Hỏi Si trong ứng dụng](/vi/docs/ask/app) --- # Gói và hạn mức > Hạn mức của từng gói (workspace, người dùng, nguồn, dung lượng, câu hỏi cho Si, cảnh báo, báo cáo, token MCP), xem mức dùng, mua thêm và điều gì xảy ra khi chạm hạn mức. Giá và tính năng đầy đủ ở [Bảng giá](/vi/pricing). Trang này giải thích hạn mức hoạt động thế nào. ## Hạn mức theo gói | Hạn mức | Miễn phí | Khởi đầu | Doanh nghiệp nhỏ | | --- | --- | --- | --- | | Workspace | 1 | 1 | 1 | | Người dùng | 1 | 5 | Không giới hạn | | Nguồn mỗi workspace | 1 (chỉ Excel) | 3 | 8 | | Dung lượng | 0,5 GB | 3 GB | 20 GB | | Câu hỏi AI mỗi tháng | 30 | 300 | 1.500 | | Cảnh báo | 0 | 5 | Không giới hạn | | Báo cáo định kỳ | 1 (hằng tuần) | 20 | Không giới hạn | | Làm mới theo lịch | Không | Mỗi giờ trở lên | Tới mỗi 15 phút | | Token MCP | Không | Không | Có | | [Nhúng dashboard](/vi/docs/dashboards/embed) | Không | Không | 5 mã, 10.000 lượt xem/tháng | | Suy nghĩ sâu | Không | Có | Có | | Si viết và chạy SQL/Python ([sandbox khám phá](/vi/docs/ask/sandbox)) | Không | Không | Có (mỗi lần chạy tính 1 câu hỏi) | Mỗi workspace có gói và hạn mức riêng. Gói Doanh nghiệp theo hợp đồng: nhiều workspace, token MCP đọc được nhiều workspace của tổ chức. Workspace mẫu không chiếm chỗ trong số workspace. ## Xem mức dùng **Cài đặt → Gói và mức dùng** (Quản trị trở lên) có ba thẻ: **Mức dùng** (đã dùng trên hạn mức), **Tính năng của gói** và **Mua thêm**. | Mua thêm | Giá | Gói | | --- | --- | --- | | 500 câu hỏi cho Si | 99.000 ₫, dùng trong kỳ đang chạy | Mọi gói | | Thêm 1 nguồn | 99.000 ₫ mỗi tháng | Khởi đầu trở lên | | Thêm 10 GB | 49.000 ₫ mỗi tháng | Mọi gói | | Thêm 10.000 lượt xem dashboard nhúng | 99.000 ₫ mỗi tháng | Doanh nghiệp nhỏ trở lên | Bấm **Nâng cấp** để chọn gói hoặc mua thêm và thanh toán trực tuyến: chuyển khoản QR bằng VND hoặc thẻ quốc tế. Gói Doanh nghiệp thanh toán theo hợp đồng. DataxLand không tự tính tiền vượt. ## Khi chạm hạn mức DataxLand chặn mềm: chỉ chặn **tạo thêm**, không bao giờ chặn xem. - Từ 80% hạn mức, Quản trị và Chủ sở hữu thấy cảnh báo. - Hết câu hỏi cho Si: tạm dừng hỏi Si (trong ứng dụng, Slack, Telegram, MCP) tới kỳ sau. Băng báo "Đã hết câu hỏi cho Si tháng này: tạm dừng hỏi Si tới kỳ sau; dashboard và báo cáo vẫn chạy." kèm link **Xem gói và mức dùng**. - Hết lượt xem dashboard nhúng: trang nhúng hiện "đang tạm dừng" tới kỳ sau; dashboard trong ứng dụng vẫn chạy. Chủ sở hữu nhận email ở 80% và 100%. - Hết chỗ nguồn, cảnh báo, báo cáo, người dùng: cái đang có vẫn dùng được; nâng cấp hoặc mua thêm để tạo thêm. - Dung lượng vượt 110%: tạm dừng làm mới và không thêm nguồn được; dashboard vẫn hiện số đã có. - Dashboard, báo cáo, cảnh báo đang chạy và [xuất dữ liệu](/vi/docs/workspace/export-delete) không bao giờ bị chặn. Gói hết hạn thì workspace về gói Miễn phí; dữ liệu giữ nguyên. Qua API, thao tác bị chặn trả lỗi HTTP 402 mã `quota_exceeded`, xem [API](/vi/docs/api/overview). ## Liên quan - [Bảng giá](/vi/pricing) - [Thành viên và vai trò](/vi/docs/workspace/members) - [Chính sách hoàn tiền](/vi/refund) --- # Cách đồng bộ và lịch làm mới > Ba cách đồng bộ dữ liệu — toàn bộ, tăng dần, CDC (đọc log) — nguồn nào hỗ trợ cách nào, và cách đặt lịch làm mới tự động. ## Ba cách đồng bộ | Cách | Hoạt động | Lưu ý | | --- | --- | --- | | **Toàn bộ** | Đọc lại cả bảng mỗi lần làm mới | Đơn giản nhất; chậm với bảng lớn | | **Tăng dần** | Chỉ đọc dòng có cột con trỏ (ví dụ `updated_at`) mới hơn lần trước, gộp theo khóa chính | Không thấy dòng bị xóa ở nguồn | | **CDC (đọc log)** | Đọc nhật ký thay đổi của database, thấy cả dòng bị xóa | Chỉ PostgreSQL; cần bật logical replication | | Nguồn | Toàn bộ | Tăng dần | CDC | | --- | --- | --- | --- | | File Excel | Có | — | — | | PostgreSQL | Có | Có | Có | | MySQL / MariaDB, SQL Server | Có | Có | — | | BigQuery, sàn, connector | Có | Có | — | Nguồn file luôn được đọc lại toàn bộ. Sàn thương mại điện tử đọc tăng dần theo thời điểm cập nhật đơn. ## Đổi cách đồng bộ 1. Vào **Nguồn dữ liệu**, thẻ **Cách đồng bộ**, bấm **Sửa cách đồng bộ**. 2. Với mỗi bảng, chọn cách. Với **Tăng dần**, chọn **Cột con trỏ** (cột có chữ "(gợi ý)" là gợi ý của DataxLand) và **Khóa chính**. 3. Bấm **Lưu cách đồng bộ**. Lần làm mới kế tiếp nạp toàn bộ một lần cho bảng đổi cấu hình. Khi tạo workspace mới, mọi bảng nạp toàn bộ; cách đồng bộ chỉ đổi được sau khi workspace đã tạo. Với CDC, đọc điều kiện ở [PostgreSQL](/vi/docs/sources/postgres#cdc). ## Lịch làm mới 1. Ở thẻ **Lịch làm mới dữ liệu**, chọn **Tần suất**: Mỗi 15 phút, Mỗi 30 phút, Mỗi giờ, Hằng ngày, Hằng tuần, Hằng tháng. 2. Chọn **Giờ chạy** (với lịch theo ngày, tuần, tháng), **Thứ** hoặc **Ngày trong tháng** (1–28). 3. Bật **Bật làm mới tự động** rồi bấm **Lưu lịch**. Mặc định hằng ngày lúc 06:00 theo múi giờ workspace. Mỗi 15 phút và mỗi 30 phút chỉ có khi mọi nguồn đồng bộ tăng dần hoặc CDC. Lịch chỉ chạy khi workspace đã duyệt. | Gói | Tần suất được dùng | | --- | --- | | Miễn phí | Không có lịch; tải file mới bằng tay (**Thay file**) | | Khởi đầu | Mỗi giờ, hằng ngày, hằng tuần, hằng tháng | | Doanh nghiệp nhỏ trở lên | Tới mỗi 15 phút | Lịch không thuộc gói hiện tại sẽ bị bỏ qua và ghi lý do. Dung lượng lưu trữ vượt 110% hạn mức thì làm mới tạm dừng, xem [Gói và hạn mức](/vi/docs/billing/quotas). ## Liên quan - [Kết nối dữ liệu](/vi/docs/connect-data) - [PostgreSQL và CDC](/vi/docs/sources/postgres) - [Số có kiểm tra](/vi/docs/data-quality) --- # Workspace > Workspace là đơn vị dữ liệu, thành viên và gói trong DataxLand — các trạng thái từ tạo tới sẵn sàng, thanh điều hướng và vai trò. Một **workspace** gom nguồn dữ liệu, kho dữ liệu riêng, chỉ số, dashboard, thành viên và gói của một doanh nghiệp, một thương hiệu hay một đơn vị. Dữ liệu của workspace này không bao giờ đọc được từ workspace khác. ## Trạng thái | Trạng thái | Nghĩa | Việc tiếp theo | | --- | --- | --- | | Đang tạo | Đang nạp nguồn | Chờ | | Đã đọc dữ liệu | Đã nạp, chưa có đề xuất | **Nhờ Si đề xuất** | | Chờ duyệt | Si đã đề xuất | **Duyệt đề xuất** hoặc **Đề xuất lại** | | Đã duyệt | Đã duyệt, chưa build | **Build** | | Sẵn sàng | Dashboard đã công bố | **Mở dashboard** | | Lỗi | Một bước bị lỗi | **Chạy tiếp** hoặc **Sửa bản duyệt** | Chỉ Quản trị và Chủ sở hữu thấy các nút ngoài dashboard. Xem [Duyệt đề xuất và build](/vi/docs/review/mapping). ## Thanh điều hướng | Nhóm | Mục | | --- | --- | | (đầu) | Workspace (danh sách workspace), Trang chính | | Báo cáo | Các trang dashboard của gói và trang của workspace | | Hỏi và tra cứu | Hỏi Si, Sổ tay chỉ số, Hiểu doanh nghiệp, Kiến thức | | Dữ liệu và kết nối | Nguồn dữ liệu, Báo cáo và cảnh báo, Duyệt đề xuất, Sức khỏe dữ liệu, Cài đặt | Mục bạn không có quyền thì bị ẩn. Thứ tự và trang hiện trên menu đổi được ở **Cài đặt → Chung → Bố cục menu và Trang chính**. ## Vai trò | Vai trò | Làm được | | --- | --- | | Chủ sở hữu | Mọi quyền, gói và thanh toán, thành viên, xóa workspace | | Quản trị | Nguồn dữ liệu, duyệt đề xuất, cài đặt, token MCP | | Phân tích | Hỏi Si, khám phá dữ liệu, tạo chỉ số và trang nháp | | Xem | Chỉ xem dashboard và trang đã lưu | Mỗi workspace có đúng một Chủ sở hữu. Xem [Thành viên và vai trò](/vi/docs/workspace/members). ## Gói ngành và phòng ban Khi tạo workspace, Si chọn **loại hình dữ liệu** gần nhất (ngành × phòng ban, ví dụ bán lẻ · kinh doanh). Loại hình quyết định mô hình chuẩn, chỉ số và trang dashboard có sẵn. Đổi được ở hộp **Loại hình dữ liệu → Đổi và để Si phân tích lại** trong lúc thiết lập. Xem [mẫu dashboard](/vi/dashboards). ## Workspace mẫu Workspace mẫu chạy trên dữ liệu giả lập, có nhãn **Demo** và không chiếm chỗ trong số workspace của gói. Xóa nó thì mất ngay, không có thời gian chờ khôi phục. ## Liên quan - [Bắt đầu nhanh](/vi/docs/quickstart) - [Múi giờ, tiền tệ và định dạng](/vi/docs/workspace/region) - [Gói và hạn mức](/vi/docs/billing/quotas) --- # Chỉ số và lớp ngữ nghĩa > Mỗi con số có một định nghĩa có phiên bản; dashboard, Si, báo cáo và MCP đọc cùng định nghĩa đó qua lớp ngữ nghĩa, kèm mức xác nhận Chuẩn, Đã duyệt hoặc Chưa xác nhận. ## Một định nghĩa cho mỗi con số Mỗi chỉ số khai báo công thức, chiều được phép (ngày, kênh, sản phẩm…), độ chi tiết thời gian (ngày, tuần, tháng), đơn vị và hướng tốt (tăng là tốt hay xấu). Dashboard, Si, báo cáo định kỳ, cảnh báo và [MCP](/vi/docs/mcp) đều lấy số qua **cùng một máy tính chỉ số**: không có SQL riêng trong dashboard hay trong câu trả lời của Si. ## Lớp ngữ nghĩa Lớp ngữ nghĩa mô tả bảng nào nối với bảng nào, chiều nào có thể dùng để tách số và bộ lọc nào hợp lệ. Một câu hỏi, một ô dashboard hay một lời gọi MCP đều là tổ hợp: | Thành phần | Ví dụ | | --- | --- | | Chỉ số | Doanh thu thuần, lãi sau phí | | Chiều | Kênh, sản phẩm, ngày | | Bộ lọc | Kênh = Shopee | | Kỳ | Tháng trước, 28 ngày qua | | So sánh | So với kỳ trước | DataxLand dựng truy vấn từ tổ hợp đó. Mô hình ngữ nghĩa của workspace xem và sửa được ở **Cài đặt → Mô hình dữ liệu** (Quản trị trở lên). ## Ba mức xác nhận | Mức | Từ đâu | Khi nào tin được | | --- | --- | --- | | **Chuẩn** | Chỉ số của gói ngành × phòng ban | Định nghĩa chung, đã kiểm bằng số kỳ vọng | | **Đã duyệt** | Chỉ số riêng của workspace (`ws.`) | Đã kiểm số và được Quản trị kích hoạt | | **Chưa xác nhận** | Câu trả lời khám phá của Si trên mô hình đã duyệt | Kiểm tra trước khi dùng như số chính thức | Mỗi con số hiển thị kèm nhãn mức xác nhận. Một câu trả lời **Chưa xác nhận** hay dùng có thể thành chỉ số của workspace, xem [Chỉ số của workspace](/vi/docs/metrics/workspace-metrics). ## Sổ tay chỉ số Trang **Sổ tay chỉ số** (nhóm **Hỏi và tra cứu**) có hai thẻ: - **Thư viện chỉ số**: mọi chỉ số đang dùng được, tìm bằng ô "Tìm chỉ số (ví dụ: lãi, hoàn, ROAS)". Bấm **Sửa mô tả** để đổi tên hiển thị, mô tả, từ đồng nghĩa và ghi chú cho workspace (không đổi công thức). Chỉ số đã sửa có nhãn **Workspace đã chỉnh**; **Khôi phục bản gốc** đưa về như gói. - **Chỉ số của workspace**: chỉ số bạn tự định nghĩa. ## Phiên bản Đổi công thức là tăng phiên bản. Phần **Nguồn** của mỗi câu trả lời ghi chỉ số, phiên bản, kỳ và "dữ liệu đến" ngày nào; [trình giải thích](/vi/docs/ask/inspector) cho thấy công thức, bộ lọc, kỳ so sánh và câu SQL đã chạy. ## Ngày và múi giờ Thời điểm lưu theo UTC; ngày nghiệp vụ theo múi giờ workspace (mặc định Asia/Ho_Chi_Minh). Tuần bắt đầu thứ Hai. Xem [Múi giờ, tiền tệ và định dạng](/vi/docs/workspace/region). ## Liên quan - [Số có kiểm tra](/vi/docs/data-quality) - [Mẫu dashboard theo ngành](/vi/dashboards) - [Lớp ngữ nghĩa trên trang tính năng](/vi/platform/semantic-layer) --- # Kiến thức của workspace > Dạy Si về doanh nghiệp của bạn bằng hướng dẫn, thuật ngữ, sự kiện kinh doanh, câu trả lời đã xác nhận và tài liệu; Si chỉ dùng mục đã duyệt. Trang **Kiến thức** (nhóm **Hỏi và tra cứu**) giữ những điều Si cần biết mà dữ liệu không nói: "đơn sỉ là đơn trên 50 sản phẩm", "tháng 3 có đợt khuyến mãi lớn", "khi nói 'lãi' ý là lãi sau phí sàn". ## Loại mục | Thẻ | Dùng cho | | --- | --- | | Hướng dẫn | Lời dặn chung khi trả lời | | Thuật ngữ | Từ riêng của doanh nghiệp và nghĩa của nó | | Sự kiện kinh doanh | Khuyến mãi, đổi giá, sự cố, có ngày hiệu lực (**Hiệu lực từ**, **Đến ngày**) | | Câu trả lời đã xác nhận | Câu hỏi và câu trả lời bạn đánh dấu là đúng | | Tài liệu | File mô tả bạn tải lên; Si đọc theo đoạn | Mục được **Ghim** luôn được đưa vào lời dặn của Si. ## Duyệt Mục mới có trạng thái **Nháp** và nằm ở thẻ **Chờ duyệt**. Si chỉ dùng mục **Đã duyệt**. Quản trị trở lên bấm **Duyệt** hoặc **Từ chối**; mục cũ thì **Lưu trữ**. Mỗi mục có **Lịch sử** sửa đổi. Nguồn của mục: **Người dùng tạo**, **Từ hỏi đáp** (từ nút **Lưu vào kiến thức** dưới một câu trả lời) hoặc **Si đề xuất** (khi bấm **Rút kiến thức** trên tài liệu hay cuộc hỏi đáp). ## Tài liệu Tải tài liệu mô tả ở thẻ **Tài liệu**. Mục **Các đoạn AI đọc** cho xem từng đoạn; bấm **Tắt với AI** để Si bỏ qua một đoạn. Tải lại tài liệu thì các sửa đổi trên đoạn bị bỏ. ## Thử tìm như Si Ô **Thử tìm như AI** cho biết Si sẽ tìm thấy mục nào với một câu hỏi, kèm độ giống. Dùng nó để kiểm tra một thuật ngữ mới có được nhận ra không. ## Liên quan - [Si](/vi/docs/si) - [Hỏi Si trong ứng dụng](/vi/docs/ask/app) - [Bảng thuật ngữ](/vi/docs/glossary) --- # Chỉ số của workspace > Tự định nghĩa chỉ số riêng cho workspace (ws.) trên cùng máy tính chỉ số, kiểm số, kích hoạt và quản lý phiên bản; duyệt chỉ số do Si đề xuất. Gói ngành × phòng ban là điểm khởi đầu, không phải giới hạn. Workspace tự thêm chỉ số với mã `ws.`, chạy trên cùng máy tính chỉ số với chỉ số chuẩn. ## Vòng đời | Trạng thái | Nghĩa | | --- | --- | | Nháp | Đang soạn hoặc vừa đổi cách tính; chưa dùng ở dashboard, Si, MCP | | Đang dùng | Đã kiểm số và được kích hoạt; hiện nhãn **Đã duyệt** | | Lưu trữ | Ngừng dùng, giữ lịch sử | ## Tạo chỉ số 1. Vào **Sổ tay chỉ số → Chỉ số của workspace**. 2. Bấm **Tạo chỉ số**. Khai báo cách tính từ các cột và chỉ số có trong mô hình ngữ nghĩa, đơn vị và chiều được phép. 3. Bấm **Lưu bản nháp**. 4. Bấm **Kiểm tra**: DataxLand tính chỉ số trên **Kỳ mẫu**, hiện **Giá trị** và so với một chỉ số đối chiếu. Kết quả ghi **Kiểm số đạt** hoặc **Kiểm số chưa đạt** kèm phiên bản. 5. Quản trị hoặc Chủ sở hữu bấm **Kích hoạt**. Vai trò Phân tích tạo, sửa và kiểm số được; kích hoạt và lưu trữ cần Quản trị trở lên. ## Chỉ số do Si đề xuất Khi bạn hỏi một câu Si phải tự ghép công thức, Si có thể đề xuất nó thành chỉ số. Đề xuất hiện ở mục **Bản nháp từ AI** với nhãn **AI đề xuất**. Kiểm tra, sửa nếu cần rồi bấm **Duyệt**, hoặc **Bỏ**. ## Phiên bản Đổi cách tính hoặc đơn vị sẽ tăng phiên bản và đưa chỉ số về **Nháp**; cần kiểm số và bật lại. Đổi tên hiển thị hay mô tả không tăng phiên bản. Báo cáo và cảnh báo dùng chỉ số đó luôn đọc phiên bản đang dùng. ## Liên quan - [Chỉ số và lớp ngữ nghĩa](/vi/docs/metrics) - [Hỏi Si trong ứng dụng](/vi/docs/ask/app) - [Ghim vào trang](/vi/docs/dashboards/pin) --- # Nhúng dashboard vào website, ứng dụng của bạn > Đặt một trang dashboard của DataxLand vào cổng thông tin, trang quản trị hay ứng dụng của bạn bằng một đoạn iframe; khóa bộ lọc, giới hạn tên miền, thu hồi bất kỳ lúc nào. Nhúng dashboard đặt **một trang dashboard** của workspace vào trang web khác. Người xem **không cần tài khoản DataxLand**: họ chỉ thấy các ô số của trang, chọn được kỳ và các bộ lọc bạn mở. Không có Hỏi Si, trình giải thích con số, sổ tay chỉ số hay đường dẫn vào app. Nhúng có từ gói **Doanh nghiệp nhỏ** trở lên (xem [Gói và giới hạn](/vi/docs/billing/quotas)): mỗi gói có số mã nhúng còn hạn và số **lượt xem mỗi tháng**. Một lượt xem là một lần trang nhúng được tải. ## Tạo mã nhúng 1. Mở trang dashboard (nhóm **Báo cáo** ở thanh bên). Nếu muốn khách chỉ thấy một phần số liệu, chọn bộ lọc trước, ví dụ **Kênh = Shop A**. 2. Bấm **Chia sẻ → Nhúng dashboard**. Mục này cần vai trò **Quản trị** trở lên. 3. Điền: - **Tên gợi nhớ**: để nhận ra mã trong danh sách (ví dụ "Cổng đối tác Shop A"). - **Tên miền được nhúng**: mỗi dòng một, dạng `https://portal.cong-ty.vn`. Dùng `https://*.cong-ty.vn` cho mọi tên miền con. `http://` chỉ dùng được cho `localhost` khi thử. Tối đa 10 tên miền. - **Hạn dùng**: 7 đến 365 ngày. - **Kỳ khi mở**: kỳ hiện lúc người xem mở trang; họ đổi được kỳ. - **Khóa bộ lọc đang chọn**: người xem không bỏ được bộ lọc này. Ô có chỉ số không lọc được theo bộ lọc khóa sẽ bị ẩn khỏi trang nhúng (để không lộ số chưa lọc). - **Người xem được lọc theo**: các chiều người xem tự chọn giá trị (ví dụ Nền tảng). 4. Bấm **Tạo mã nhúng**, rồi **Sao chép mã iframe** (hoặc **Sao chép đường dẫn**). **Mã chỉ hiện lần này**; mất thì tạo mã mới và thu hồi mã cũ. Đoạn mã có dạng: ```html ``` Dán vào trang HTML, CMS hay ứng dụng web ở **đúng tên miền đã khai báo**. Trình duyệt chặn khung ở mọi tên miền khác (DataxLand gửi header `Content-Security-Policy: frame-ancestors` theo danh sách của mã). ## Người xem thấy gì - Tiêu đề trang, bộ chọn kỳ, bộ lọc được mở, nhãn bộ lọc khóa (biểu tượng ổ khóa). - Các ô số của trang, định dạng theo **tiền tệ, múi giờ, kiểu số** của workspace ([cài đặt vùng](/vi/docs/workspace/region)), kèm nhãn mức xác nhận **Chuẩn** như trong app. - Số đi qua cùng lớp chỉ số với app: một định nghĩa cho mọi nơi, không có thông tin cá nhân người mua. ## Quản lý và thu hồi Hộp thoại **Nhúng dashboard** liệt kê mã của trang: tên miền, hạn, **lượt xem tháng này**, trạng thái (**Đang dùng**, **Hết hạn**, **Đã thu hồi**). Bấm **Thu hồi** để dừng: trang nhúng báo "đã bị thu hồi" ở lần tải kế tiếp. Mã thuộc **workspace**, không thuộc người tạo: thành viên rời workspace thì mã vẫn chạy cho tới khi Quản trị thu hồi. Mỗi lần tạo và thu hồi được ghi vào nhật ký bảo mật của workspace. ## Hết lượt xem, hạ gói - Từ **80%** lượt xem của tháng, Chủ sở hữu nhận email và thấy thông báo trong app. - Hết lượt xem: trang nhúng hiện "đang tạm dừng" tới kỳ sau; dashboard trong app không bị ảnh hưởng. Mua thêm **10.000 lượt xem** hoặc nâng cấp gói. - Hạ xuống gói không có nhúng: mọi trang nhúng tạm dừng; mã còn trong danh sách và chạy lại khi nâng cấp (nếu chưa hết hạn). ## An toàn - `frame-ancestors` chặn trang **khác** đặt khung, nhưng **ai có đường dẫn đều mở được trang nhúng** (như một đường link chia sẻ). Với số liệu nhạy cảm: chỉ đặt iframe trong khu vực cần đăng nhập ở phía bạn, đặt hạn ngắn, khóa bộ lọc, và thu hồi ngay khi lộ mã. - Trang nhúng không gửi đường dẫn (có mã) cho trang khác (`no-referrer`), không được lưu cache, không được công cụ tìm kiếm lập chỉ mục. - Số trên trang nhúng tuân theo [quyền dữ liệu theo dòng](/vi/docs/workspace/data-access) của người tạo mã: nếu người tạo chỉ được xem một chi nhánh, trang nhúng cũng chỉ có số của chi nhánh đó. Người tạo rời workspace thì trang nhúng dừng hiện số. - Mỗi mã nhúng một trang dashboard của gói. Cần lọc theo từng người xem đăng nhập ở hệ thống của bạn: liên hệ DataxLand. ## Liên quan - [Dashboard và ghim vào trang](/vi/docs/dashboards/pin) - [Gói và giới hạn](/vi/docs/billing/quotas) - [Bảo mật và quyền riêng tư](/vi/docs/security-privacy) --- # Trang của workspace > Tạo trang riêng, thêm và sửa ô trên lớp ngữ nghĩa không cần SQL, dùng chung trang với cả workspace, giữ hoặc bỏ ô nháp do Si ghim, xem lịch sử. Ngoài dashboard của gói, mỗi người trong workspace có thể dựng trang riêng: một bộ ô bạn chọn, xếp theo cách bạn đọc. ## Tạo trang Trang được tạo theo ba cách: - khi ghim: **+ Tạo trang mới (riêng)** (xem [Ghim vào trang](/vi/docs/dashboards/pin)); - **Sao chép trang** trên một dashboard: tạo "… (bản sao)" để sửa; - nhờ Si ghim một kết quả vào trang mới. ## Sửa trang 1. Mở trang, bấm **Sửa trang**. 2. **Thêm ô** hoặc sửa ô có sẵn. Mỗi ô là một truy vấn trên lớp ngữ nghĩa (chỉ số, chiều, bộ lọc, kỳ); không viết SQL. 3. Bấm **Xem trước**, rồi **Cập nhật ô**. 4. Bấm **Lưu trang** (hoặc **Hủy**). **Lịch sử** cho xem các lần sửa; **Xóa trang** để xóa. ## Riêng và dùng chung | Nhãn | Ai thấy | | --- | --- | | Riêng | Chỉ người tạo | | Dùng chung | Mọi thành viên workspace, kể cả vai trò Xem | Đánh dấu **Dùng chung với mọi người trong workspace** khi sửa trang. Tạo, sửa và chia sẻ trang cần vai trò Phân tích trở lên. Vai trò Xem không thấy trang riêng và ô nháp. ## Ô nháp của Si Khi Si ghim, trang báo "Trang có ô nháp do AI ghim; bấm Lưu để giữ hoặc Bỏ để xóa từng ô". Mỗi ô nháp có nhãn **Nháp** và hai nút **Lưu** / **Bỏ**. Ô báo **Ô này chưa hiện được số** khi chỉ số không còn dùng được (ví dụ chỉ số của workspace đã lưu trữ). ## Menu và Trang chính Quản trị đổi thứ tự trang, ẩn hoặc hiện trang trên menu và chọn Trang chính ở **Cài đặt → Chung → Bố cục menu và Trang chính**, rồi **Lưu bố cục**. ## Liên quan - [Dashboard và ghim vào trang](/vi/docs/dashboards/pin) - [Báo cáo và cảnh báo](/vi/docs/alerts-reports) - [Chỉ số và lớp ngữ nghĩa](/vi/docs/metrics) --- # Dashboard và ghim vào trang > Đọc dashboard của gói (kỳ, bộ lọc, Vì sao?), chia sẻ, và ghim một kết quả từ trình giải thích hay câu trả lời của Si vào trang của bạn. ## Đọc dashboard Các trang trong nhóm **Báo cáo** của thanh bên là dashboard của gói, dựng sau khi build. - **Kỳ**: 7 ngày qua, 28 ngày qua, **90 ngày qua** (mặc định), Tháng này, Tháng trước, Tùy chỉnh, rồi **Áp dụng**. - **Bộ lọc**: **Thêm bộ lọc → Lọc theo** (ví dụ kênh), **Áp dụng**; **Xóa bộ lọc** để bỏ. - **Ô số**: dòng **Kỳ trước** cho so sánh; bấm **Vì sao?** để mở [trình giải thích](/vi/docs/ask/inspector) ở thẻ **Vì sao thay đổi**. Nút **Chi tiết** trên mỗi ô (hoặc bấm vào một cột, một điểm của biểu đồ) mở trình giải thích: tóm tắt, phân tách, SQL. - **Hỏi Si**: nút ở thanh trên mở khung hỏi Si về trang đang xem, với gợi ý như "Tóm tắt trang này". Đầu trang có **Sao chép trang** (tạo bản sao riêng để sửa) và **Chia sẻ**: **Lên lịch báo cáo**, **Đặt cảnh báo**, **Gửi tới Google Sheets**, [**Nhúng dashboard**](/vi/docs/dashboards/embed) (đặt trang vào website của bạn, Quản trị trở lên). ## Ghim vào trang Ô ghim **chạy lại đúng truy vấn đó mỗi khi mở trang**, với số mới nhất; không phải ảnh chụp. 1. Mở kết quả cần ghim: - trên dashboard: bấm **Chi tiết** trên ô, **Vì sao?**, hoặc bấm vào một điểm của biểu đồ để mở trình giải thích; - trong **Hỏi Si**: sửa **Cách hiểu câu hỏi** nếu cần rồi bấm **Chạy lại**; thẻ kết quả có nút ghim. 2. Bấm **Ghim vào trang**. 3. Đặt **Tiêu đề ô**, chọn **Loại biểu đồ** và trang đích. Trang riêng ghi "(riêng)". Chọn **+ Tạo trang mới (riêng)** và điền **Tên trang mới** để tạo trang. 4. Bấm **Ghim**. Thông báo **Đã ghim vào trang …** có nút **Mở trang**. Si cũng ghim được khi bạn nhờ ("ghim biểu đồ này vào trang Theo dõi kênh"). Ô do Si ghim có nhãn **Nháp** cho tới khi bạn bấm **Lưu** trên trang. Ghim cần vai trò Phân tích trở lên. ## Liên quan - [Trang của workspace](/vi/docs/dashboards/pages) - [Nhúng dashboard vào website của bạn](/vi/docs/dashboards/embed) - [Trình giải thích con số](/vi/docs/ask/inspector) - [Mẫu dashboard theo ngành](/vi/dashboards) --- # Duyệt đề xuất và build > Xem Si sẽ dựng những chỉ số và trang dashboard nào, câu trả lời và giả định của bạn, sửa ánh xạ ở màn Duyệt đề xuất (ô tô vàng), duyệt rồi build và theo dõi tiến trình tới khi dashboard sẵn sàng. Không có gì được build khi workspace chưa được duyệt. Duyệt cần vai trò Quản trị hoặc Chủ sở hữu. ## 1. Bước Duyệt và build Thẻ **Duyệt và build** tóm tắt điều sẽ xảy ra: | Phần | Nội dung | | --- | --- | | Si hiểu dữ liệu của bạn | Lĩnh vực, dữ liệu nói về gì, mỗi dòng là gì | | Si sẽ dựng | Số chỉ số và trang dashboard; từng trang kèm thẻ chính; cách tính từng chỉ số. Dữ liệu không có cột ngày thì chỉ số là số hiện có, không so theo kỳ | | Chỉ số chưa có | Với mẫu phân tích có sẵn: chỉ số tạm ẩn và lý do, ví dụ "Chưa đủ dữ liệu để tính." | | Dữ liệu cần thêm cho các chỉ số chưa có | Trường mà các chỉ số tạm ẩn của chính mẫu đang dùng cần | | Câu trả lời của bạn | Lựa chọn ở bước Làm rõ và xem lại | | Giả định | Cách hiểu Si dùng khi dựng dashboard, bạn đã chấp nhận ở bước trước | | Phạm vi nạp dữ liệu | Bảng và khoảng ngày được nạp | Mọi điều Si chưa chắc đã được hỏi ở bước **Làm rõ và xem lại** hoặc ghi thành giả định, nên bước này không còn mục "chưa chắc". Giả định chưa đúng thì bấm **Quay lại** để chọn lại. Mở **Bố cục menu và Trang chính** để xem menu Si đề xuất. Bấm **Duyệt và build**, hoặc **Quay lại** để sửa. ## 2. Sửa chi tiết ở màn Duyệt đề xuất Màn **Duyệt đề xuất** (nhóm **Dữ liệu và kết nối**) cho sửa từng phần. **Ô tô vàng là chỗ Si chưa chắc (điểm dưới 80%)**. | Thẻ | Sửa gì | | --- | --- | | Mô hình nghiệp vụ | Doanh nghiệp bán gì, qua kênh nào, mỗi bảng là gì | | Ánh xạ | Cột nguồn nào vào trường chuẩn nào (mã đơn, ngày, số tiền, phí…) | | Trạng thái | Trạng thái nguồn tương ứng trạng thái chuẩn; **mọi dòng phải có trạng thái chuẩn trước khi duyệt** | | Câu hỏi mở | Câu hỏi Si còn chờ | | Chỉ số | Chỉ số bật hoặc tắt; chỉ số "Chưa chắc" chỉ bật khi bạn đánh dấu **Tôi hiểu con số này có thể sai** | Chuyển giữa **Đề xuất mới nhất** và **Bản đã duyệt** để so sánh. Muốn Si làm lại, mở **Đề xuất lại**, ghi **Ghi chú cho Si (tùy chọn)** và chạy. Khung bên phải **Câu hỏi và duyệt** có nút **Duyệt** (chỉ duyệt) và **Duyệt và build**. Với PostgreSQL và BigQuery, mục **Nâng cao: chạy SQL trên nguồn** cho bạn tự chạy SQL chỉ đọc để kiểm tra rồi **Phân tích lại**. ## 3. Build Build chạy nền; bạn đóng trang được. Tiến trình ghi từng bước: **Mở kho build**, **Nạp dữ liệu**, **Sinh model**, **Biến đổi dữ liệu**, **Kiểm tra chất lượng**, đối chiếu số, **Công bố**. Trạng thái mỗi bước: Chờ, Đang chạy, Xong, Bị chặn, Lỗi. - **Xong**: workspace **Sẵn sàng**, bấm **Mở dashboard**. - **Bị chặn**: một kiểm tra mức chặn không đạt hoặc số không khớp nguồn; xem [Số có kiểm tra](/vi/docs/data-quality). - **Lỗi**: bấm **Chạy tiếp** sau khi sửa, hoặc **Sửa bản duyệt**. ## Duyệt lại sau này Thêm nguồn, đổi loại hình hay sửa ánh xạ đều tạo đề xuất mới. Dashboard đang dùng vẫn chạy trên bản đã duyệt cho tới khi bạn duyệt và build bản mới. ## Liên quan - [Trả lời câu hỏi của Si](/vi/docs/review/questions) - [Workspace: các trạng thái](/vi/docs/concepts/workspace) - [Ghim vào trang](/vi/docs/dashboards/pin) --- # Che thông tin cá nhân > Bước Chọn dữ liệu và thông tin cá nhân — chọn cột cần che, cho phép hoặc không lưu giá trị gốc, chọn vùng xử lý và đồng ý gửi mẫu đã che cho Si. Sau khi đọc nguồn, bước **Chọn dữ liệu và thông tin cá nhân** hỏi bạn cột nào là thông tin cá nhân. Bước này do Quản trị hoặc Chủ sở hữu làm. ## Chọn cột cần che Màn **Chọn cột cần che** chia hai nhóm: - **Cột nghi ngờ chứa thông tin cá nhân**: tên, số điện thoại, email, địa chỉ… mà DataxLand nhận ra. - **Các cột khác**: đánh dấu thêm nếu một cột có thông tin cá nhân mà DataxLand bỏ sót. Cột đánh dấu `pii` trong `data_dictionary` ghi **Từ data dictionary, luôn được che** và không bỏ dấu được. Cột chữ tự do (ghi chú, nội dung tin nhắn) được che mặc định vì hay chứa số điện thoại hay địa chỉ. ## Che và băm nghĩa là gì - **Che**: giá trị không bao giờ vào prompt của Si; Si chỉ thấy dạng đã che. - **Băm**: ngay khi nạp, giá trị được thay bằng mã băm có salt riêng của workspace. Vẫn đếm được khách hàng duy nhất, vẫn nối được bảng, nhưng không đọc ngược ra giá trị gốc. ## Lưu giá trị gốc Ô **Cho phép lưu giá trị gốc của các cột trên trong kho riêng của workspace** mặc định tắt. Bật nó thì giá trị gốc được lưu trong kho riêng (vẫn che với Si và không trả qua API, Si hay MCP). Thay đổi có hiệu lực từ lần đọc kế tiếp. Chỉ bật khi bạn có cơ sở pháp lý để lưu. ## Vùng xử lý và đồng ý 1. Chọn **Vùng xử lý dữ liệu**. 2. Đánh dấu **Tôi đồng ý gửi tới 1.000 dòng mẫu đã che…** để Si đọc mẫu. 3. Bấm **Xác nhận và để Si phân tích**. Si bắt đầu phân tích, thường mất 1–3 phút. Mỗi khi thêm hoặc gỡ nguồn, bạn quay lại bước này cho dữ liệu mới. ## Liên quan - [Trả lời câu hỏi của Si](/vi/docs/review/questions) - [Bảo mật và quyền riêng tư](/vi/docs/security-privacy) - [File Excel: sheet data_dictionary](/vi/docs/sources/excel) --- # Trả lời câu hỏi của Si > Bước Làm rõ và xem lại — Si cho biết đã hiểu dữ liệu thế nào rồi hỏi vài câu lựa chọn về điều bạn muốn theo dõi, cột khó hiểu và dòng thiếu dữ liệu; cách trả lời, thêm bối cảnh và đổi loại hình dữ liệu. Si không đoán ở chỗ không chắc: Si hỏi bạn. Bước **Làm rõ và xem lại** có hai phần: **Si hiểu dữ liệu của bạn** và **Si cần bạn chọn**. ## Si hiểu dữ liệu của bạn Si đọc mọi loại dữ liệu: bán hàng, nhân sự, tài chính, vận hành, marketing, giáo dục, y tế… Phần này nêu lĩnh vực, dữ liệu nói về gì và vài câu hỏi dữ liệu trả lời được. Mục **Ghi chú về dữ liệu** (thu gọn) liệt kê điều đáng lưu ý, ví dụ tên schema không khớp nội dung hay cột luôn một giá trị; các ghi chú này không chặn việc dựng dashboard. Dữ liệu không có cột ngày vẫn dựng được dashboard: chỉ số là **số hiện có** của dữ liệu đã nạp (ví dụ số nhân viên, tỷ lệ nghỉ việc), không so theo kỳ. ## Câu hỏi lựa chọn Mỗi câu có 2–4 lựa chọn, một lựa chọn gắn nhãn **Si đề xuất** và đã được chọn sẵn. Câu chọn được nhiều đáp án có ghi "Chọn được nhiều mục". Không có đáp án phù hợp thì chọn **Khác** rồi ghi rõ; Si lưu ghi chú này làm bối cảnh cho lần phân tích sau. Ví dụ: - **Bạn muốn theo dõi điều gì trước?** (tỷ lệ nghỉ việc, chi phí lương, mức độ hài lòng, cơ cấu nhân sự): chỉ số bạn chọn lên trang **Trọng tâm** đứng đầu và lên Trang chính; - **monthlyrate, hourlyrate, dailyrate là gì?** (số tiền, con số thường, bỏ qua): Si chọn đơn vị và cách tính theo câu trả lời; - **Có khoảng 29 dòng thiếu phòng ban và vị trí. Giữ hay loại?**: giữ thì các dòng này ghi là "Chưa rõ", loại thì không tính vào mọi chỉ số của bảng; - **Si chưa chắc: … Cách hiểu này có đúng không?**: điều Si chưa kiểm chứng được, bạn xác nhận hoặc ghi lại cách hiểu đúng. Với mẫu phân tích có sẵn (ví dụ bán hàng đa kênh), Si còn hỏi về ánh xạ, ví dụ trạng thái đơn nào là đơn hủy. Trả lời rồi bấm **Lưu và tiếp tục**. Câu trả lời và giả định được lưu cùng bản duyệt; lần sau Si phân tích lại, câu trả lời cũ là lựa chọn đề xuất. ## Ánh xạ chưa chắc Với mẫu phân tích có sẵn, mục **Si chưa chắc chắn về N mục ánh xạ** ghi độ tin cậy từng mục (ví dụ 62%). Mục **Mô tả chi tiết của Si về dữ liệu** là bản mô tả đầy đủ. Sửa chi tiết ở màn duyệt nâng cao, xem [Duyệt đề xuất và build](/vi/docs/review/mapping). ## Thêm bối cảnh Ô **Bối cảnh dữ liệu cho Si (không bắt buộc)** nhận ghi chú (**Lưu ghi chú**) và tài liệu mô tả (**Tải tài liệu mô tả**). Bấm **Rút kiến thức** để Si rút thuật ngữ, quy tắc từ tài liệu thành mục [Kiến thức](/vi/docs/metrics/knowledge) chờ duyệt. Sau khi thêm bối cảnh, bấm **Để Si phân tích lại**. ## Đổi loại hình dữ liệu Không mẫu phân tích có sẵn nào hợp thì Si dựng gói riêng từ chính các cột của dữ liệu. Nếu muốn dùng một mẫu khác, ở hộp **Loại hình dữ liệu** chọn **Đổi loại hình** rồi **Đổi và để Si phân tích lại**. ## Liên quan - [Che thông tin cá nhân](/vi/docs/review/pii) - [Duyệt đề xuất và build](/vi/docs/review/mapping) - [Si](/vi/docs/si) --- # BigQuery > Nối BigQuery bằng khóa service account, chọn project chạy truy vấn và dataset, đặt giới hạn dung lượng quét để kiểm soát chi phí. BigQuery cần gói Khởi đầu trở lên. DataxLand chạy truy vấn đọc trên project bạn chỉ định (Google tính phí quét dữ liệu vào project đó) và chép kết quả về kho riêng của workspace. ## 1. Chuẩn bị trên Google Cloud 1. Tạo một service account riêng cho DataxLand. 2. Cấp vai trò **BigQuery Job User** trên project chạy truy vấn và **BigQuery Data Viewer** trên dataset cần đọc (nếu dữ liệu nằm cùng project thì cấp cả hai ở project đó). 3. Tạo khóa dạng **JSON** cho service account và tải file về. ## 2. Kết nối 1. **Nguồn dữ liệu → Thêm nguồn**, chọn **BigQuery**. 2. **Project chạy truy vấn (trả phí)**: project được tính phí quét. 3. **Dataset**: `dataset` hoặc `project.dataset` (thêm `.bảng` để chỉ đọc một bảng). 4. **Giới hạn dung lượng quét**: số byte tối đa mỗi truy vấn được quét, mặc định 2 GB. Truy vấn vượt giới hạn bị dừng trước khi chạy, kèm thông báo dung lượng ước tính. 5. **Khóa service account**: dán nội dung file JSON, hoặc **Hoặc chọn file JSON**. 6. Bấm **Kiểm tra kết nối**, chọn bảng ở **Chọn bảng cần đọc** (tùy chọn **Lọc theo ngày**) rồi thêm nguồn. Khóa được mã hóa khi lưu và không hiển thị lại (thẻ nguồn ghi **Đã lưu mật khẩu**). ## 3. Đồng bộ BigQuery hỗ trợ **Toàn bộ** và **Tăng dần**. Bảng lớn nên đồng bộ tăng dần theo cột thời gian cập nhật để giảm dung lượng quét. Xem [Cách đồng bộ và lịch làm mới](/vi/docs/concepts/sync-modes). ## Si điều tra bằng SQL Si được chạy SQL chỉ đọc trên BigQuery khi điều tra, trong cùng giới hạn dung lượng quét; câu vượt giới hạn chờ bạn xác nhận. ## Liên quan - [PostgreSQL](/vi/docs/sources/postgres) - [Kết nối dữ liệu](/vi/docs/connect-data) - [Gói và hạn mức](/vi/docs/billing/quotas) --- # Thư viện connector > Hơn 560 connector cho quảng cáo, CRM, thanh toán, phân tích, bảng tính — cách tìm, chọn nhiều nguồn cùng lúc, điền form, kiểm tra kết nối và chọn luồng dữ liệu. Ngoài nguồn của DataxLand (Excel, PostgreSQL, BigQuery, REST API, các sàn), thư viện có **hơn 560 connector** dựa trên giao thức Airbyte mã nguồn mở: quảng cáo, CRM, thanh toán, phân tích, bảng tính, công cụ làm việc. Connector chạy trên máy chủ DataxLand; bạn không cần cài hay biết Airbyte. Cần gói Khởi đầu trở lên. ## Tìm connector - Ô **Tìm connector**: gõ tên ứng dụng, ví dụ Shopee, Google Sheets, quảng cáo. - Lọc theo nhóm (bắt đầu bằng **Tất cả**). Mục **Kết nối của DataxLand** luôn ở trên cùng. - Nhãn hỗ trợ: | Nhãn | Nghĩa | | --- | --- | | DataxLand | Do DataxLand viết và bảo trì | | Chính thức | Connector được chứng nhận trong hệ Airbyte | | Cộng đồng | Do cộng đồng đóng góp; chất lượng không đồng đều, hãy thử kết nối trước | Xem toàn bộ danh mục ở [/vi/connectors](/vi/connectors). ## Chọn và cấu hình 1. Bấm **Chọn** trên một hay nhiều connector; thanh dưới ghi **Đã chọn N connector**. Bấm **Tiếp tục**. 2. Mỗi connector một bước. Ô có dấu * là bắt buộc. Liên kết **Hướng dẫn lấy thông tin kết nối** mở tài liệu của nhà cung cấp. 3. Bấm **Kiểm tra kết nối**. Thấy **Không kết nối được** thì đọc thông báo lỗi, thường là khóa sai hoặc thiếu quyền. 4. Ở **Chọn luồng dữ liệu (stream) cần đọc**, đánh dấu luồng cần dùng (**Chọn tất cả** để lấy hết). 5. Ở **Xem lại trước khi thêm**, kiểm tra rồi bấm **Thêm N nguồn**. Ô mật khẩu được mã hóa khi lưu và không hiển thị lại. ## Sau khi thêm DataxLand đọc dữ liệu, bạn xác nhận lại cột cần che, Si đề xuất lại ánh xạ cho nguồn mới. Connector hỗ trợ đồng bộ **Toàn bộ** và **Tăng dần**. Xem [Cách đồng bộ và lịch làm mới](/vi/docs/concepts/sync-modes). ## Không thấy phần mềm của bạn Nếu phần mềm có REST API trả JSON, dùng [REST API tùy biến](/vi/docs/sources/rest-api). Nếu không, xuất ra Excel và dùng [File Excel](/vi/docs/sources/excel). ## Liên quan - [Kết nối dữ liệu](/vi/docs/connect-data) - [Che thông tin cá nhân](/vi/docs/review/pii) --- # File Excel > Chuẩn bị file .xlsx cho DataxLand — mỗi sheet một bảng, sheet data_dictionary mô tả cột, giới hạn kích thước — rồi tải lên và thay file khi có số mới. ## 1. Mỗi sheet là một bảng - Dòng 1 là tên cột. Không để ô tiêu đề trống, không có hai cột cùng tên. - Mỗi sheet tối đa 200.000 dòng; cả file tối đa 50 MB. Sheet trống bị bỏ qua kèm cảnh báo. - Tên sheet và tên cột được đổi về chữ thường không dấu, nối bằng dấu gạch dưới (`Mã đơn` → `ma_don`). - Giá trị được nạp nguyên trạng dạng chữ; kiểu số, ngày được suy ra ở bước sau. ## 2. Sheet `data_dictionary` Sheet này giúp Si hiểu nhanh và đúng hơn. Thiếu nó DataxLand vẫn đọc file, kèm cảnh báo "kiểu và ý nghĩa cột được suy ra từ dữ liệu". Có nó thì phải đủ bốn cột bắt buộc. | Cột | Bắt buộc | Nội dung | | --- | --- | --- | | `table_name` | Có | Tên sheet | | `column_name` | Có | Tên cột; `*` là dòng mô tả cả bảng | | `data_type` | Có | Kiểu trong hệ thống gốc, ví dụ `VARCHAR(50)`, `DECIMAL(15,0)`, `DATE` | | `description` | Có | Ý nghĩa của cột | | `key` | Không | `PK`, `FK` hoặc `PK, FK`; nhiều cột `PK` là khóa ghép | | `references` | Không | Cột được tham chiếu, ví dụ `products.sku` | | `pii` | Không | `Y` nếu là thông tin cá nhân (tên, điện thoại, email, địa chỉ) | Cột đánh dấu `pii = Y` luôn bị che, không bỏ dấu được ở bước chọn cột. ## 3. Tải lên 1. Khi tạo workspace (hoặc **Nguồn dữ liệu → Thêm nguồn**), chọn thẻ **File Excel** và bấm **Tải file lên**. 2. Chọn file ở ô **File dữ liệu (.xlsx)**. Chỉ nhận `.xlsx`. 3. Bấm **Tạo workspace và đọc dữ liệu** (hoặc thêm nguồn). Lỗi chặn (ô tiêu đề trống, cột trùng tên, quá số dòng) hiện kèm tên sheet. ## 4. Thay file khi có số mới Gói Miễn phí không có lịch làm mới. Khi có số mới, vào **Nguồn dữ liệu**, thẻ **Thay file**, chọn **File mới (.xlsx)** và bấm **Thay file và làm mới**. Giữ nguyên tên sheet và tên cột để ánh xạ đã duyệt vẫn dùng được. ## Liên quan - [Che thông tin cá nhân](/vi/docs/review/pii) - [Bắt đầu nhanh](/vi/docs/quickstart) - [Trang connector Excel](/vi/connectors/excel) --- # Lazada > Kết nối Lazada bằng nút Kết nối với Lazada (OAuth) để đọc đơn hàng, giao dịch tài chính, thanh toán, trả hàng và sản phẩm, ở Việt Nam và các nước Lazada hoạt động. Kết nối Lazada cần gói Khởi đầu trở lên. Hỗ trợ shop ở Việt Nam, Thái Lan, Singapore, Malaysia, Philippines và Indonesia. ## Kết nối 1. Khi tạo workspace: nhập **Tên workspace** trước. Với workspace đã có: **Nguồn dữ liệu → Thêm nguồn**. 2. Bấm **Kết nối với Lazada** (hoặc đánh dấu **Thêm vào danh sách, kết nối sau cùng các connector khác**). 3. Trên trang Lazada, đăng nhập tài khoản người bán và đồng ý cấp quyền. 4. Quay về DataxLand: **Đã kết nối nguồn Lazada**. Mặc định đọc **90 ngày gần nhất**; các lần sau đọc tăng dần. ## Dữ liệu được đọc | Bảng | Nội dung | | --- | --- | | `orders` | Đơn hàng | | `order_items` | Dòng hàng | | `finance_transactions` | Giao dịch tài chính: phí, hoa hồng, điều chỉnh | | `payouts` | Các lần thanh toán về tài khoản | | `returns` | Trả hàng, hoàn tiền | | `products` | Sản phẩm | ## Khi không kết nối được - **Chưa cấu hình khóa ứng dụng**: kết nối Lazada chưa mở trên máy chủ này. Tạm thời dùng file xuất từ Seller Center với [File Excel](/vi/docs/sources/excel). - **Chưa kết nối được với sàn**: thử lại; kiểm tra bạn đăng nhập đúng tài khoản người bán. ## Liên quan - [Shopee](/vi/docs/sources/shopee) · [TikTok Shop](/vi/docs/sources/tiktok-shop) - [Kết nối dữ liệu](/vi/docs/connect-data) --- # SQL Server / Azure SQL > Nối Microsoft SQL Server, Azure SQL Database, Azure SQL Managed Instance, Amazon RDS for SQL Server bằng người dùng chỉ đọc, nạp toàn bộ hoặc tăng dần theo rowversion hay cột cập nhật. SQL Server / Azure SQL cần gói Khởi đầu trở lên. DataxLand nói thẳng giao thức TDS (không cần cài ODBC driver), đọc theo luồng và chép bảng bạn chọn về kho riêng của workspace; DataxLand chỉ chạy câu `SELECT`, không ghi vào database của bạn. Phiên đọc đặt `DEADLOCK_PRIORITY LOW` và chờ khóa tối đa 60 giây để không cản ứng dụng đang chạy. Dùng được với SQL Server 2016 trở lên, Azure SQL Database, Azure SQL Managed Instance và Amazon RDS for SQL Server. ## 1. Chuẩn bị người dùng Tạo login và user riêng cho DataxLand, chỉ có quyền đọc: ```sql -- trên master (Azure SQL Database: tạo "contained user" ngay trong database, bỏ dòng CREATE LOGIN) CREATE LOGIN dataxland WITH PASSWORD = ''; -- trên database cần nạp CREATE USER dataxland FOR LOGIN dataxland; -- Azure SQL: CREATE USER dataxland WITH PASSWORD = ''; ALTER ROLE db_datareader ADD MEMBER dataxland; -- hoặc: GRANT SELECT ON SCHEMA::dbo TO dataxland; GRANT VIEW DEFINITION TO dataxland; -- đọc khóa chính, khóa ngoại, mô tả cột GRANT SHOWPLAN TO dataxland; -- ước tính chi phí câu SQL của Si (không bắt buộc) ``` Thiếu `SHOWPLAN` thì mọi câu SQL Si muốn chạy trên nguồn đều chờ người kỹ thuật xác nhận. Nếu database chỉ mở cho IP nhất định (tường lửa Azure, security group), mở cho địa chỉ máy chủ DataxLand (hỏi đội hỗ trợ). ## 2. Kết nối 1. **Nguồn dữ liệu → Thêm nguồn**, chọn **SQL Server / Azure SQL**. 2. Điền **Máy chủ** (ví dụ `ten-may-chu.database.windows.net`; không kèm `\tên-instance` hay `,cổng`), **Cổng** (mặc định 1433; instance có tên thì dùng cổng cố định của instance), **Tên database**, **Schema** (mặc định `dbo`), **Người dùng**, **Mật khẩu**. 3. **SSL**: - **require** (mặc định): bắt buộc mã hóa, chấp nhận chứng chỉ tự ký (như `TrustServerCertificate=yes`), hợp với SQL Server tự cài. - **verify-full**: bắt buộc mã hóa và kiểm chứng chỉ do CA công khai cấp, đúng tên máy chủ. Nên dùng cho Azure SQL. - **disable**: không mã hóa, chỉ dùng trong mạng tin cậy; máy chủ bắt buộc mã hóa thì sẽ từ chối. 4. Bấm **Kiểm tra kết nối**, chọn bảng (tùy chọn **Lọc theo ngày**), rồi thêm nguồn. Mật khẩu được mã hóa khi lưu và không hiển thị lại. ## 3. Cách đồng bộ SQL Server có **Toàn bộ** và **Tăng dần**. Với tăng dần, cột con trỏ tốt nhất là một cột kiểu **`rowversion`**: SQL Server tự tăng nó ở mọi lần thêm hoặc sửa dòng, nên không sót thay đổi nào kể cả khi ứng dụng quên cập nhật `updated_at`. DataxLand gợi ý cột rowversion trước, rồi tới cột thời điểm như `updated_at`. Bảng chưa có thì thêm (không đổi dữ liệu cũ): ```sql ALTER TABLE dbo.orders ADD row_version ROWVERSION; ``` Mốc rowversion không vượt qua giao dịch còn mở lúc bắt đầu đọc (`MIN_ACTIVE_ROWVERSION()`), nên dòng ghi xong muộn vẫn được đọc ở lần sau. Với cột thời điểm, mỗi lần đọc lùi 10 phút cho an toàn. Tăng dần không thấy dòng bị xóa; Change Tracking / CDC của SQL Server sẽ có sau. Xem [Cách đồng bộ và lịch làm mới](/vi/docs/concepts/sync-modes). ## Kiểu dữ liệu | Kiểu SQL Server | Trong từ điển | Ghi chú | | --- | --- | --- | | `tinyint`, `smallint`, `int`, `bigint`, `rowversion` | BIGINT | rowversion đọc ra số | | `decimal`, `numeric`, `money`, `smallmoney`, `float`, `real` | DECIMAL | | | `bit` | BOOLEAN | `true`/`false` | | `date` | DATE | | | `datetime`, `datetime2`, `smalldatetime`, `datetimeoffset` | DATETIME | `datetimeoffset` đổi về giờ Việt Nam | | `char`, `varchar`, `nchar`, `nvarchar`, `text`, `xml`, `uniqueidentifier`, `time` | VARCHAR | | | `geography`, `geometry`, `hierarchyid` | VARCHAR | đọc ra chữ (WKT) | | `binary`, `varbinary`, `image` | (bỏ trống) | dữ liệu nhị phân không dùng | ## Si điều tra bằng SQL Si được chạy SQL chỉ đọc trên nguồn khi điều tra, trong giới hạn số câu và chi phí (ước tính bằng `SHOWPLAN_XML`, câu chưa chạy); câu vượt giới hạn chờ người kỹ thuật xác nhận. ## Liên quan - [PostgreSQL](/vi/docs/sources/postgres) - [MySQL / MariaDB](/vi/docs/sources/mysql) - [Bảo mật và quyền riêng tư](/vi/docs/security-privacy) --- # MySQL / MariaDB > Nối MySQL, MariaDB (kể cả Amazon RDS, Aurora, Azure Database for MySQL, Cloud SQL) bằng người dùng chỉ đọc, chọn bảng, nạp toàn bộ hoặc tăng dần theo cột cập nhật. MySQL / MariaDB cần gói Khởi đầu trở lên. DataxLand chép bảng bạn chọn về kho riêng của workspace qua một phiên **chỉ đọc** (`SET SESSION TRANSACTION READ ONLY`), đọc theo luồng nên bảng lớn không làm đầy bộ nhớ; DataxLand không ghi vào database của bạn. Dùng được với MySQL 5.7, 8.x, MariaDB 10.x, 11.x và các dịch vụ tương thích (Amazon RDS, Aurora MySQL, Azure Database for MySQL, Google Cloud SQL). ## 1. Chuẩn bị người dùng Tạo một người dùng riêng cho DataxLand, chỉ có quyền đọc database cần nạp: ```sql CREATE USER 'dataxland'@'%' IDENTIFIED BY ''; GRANT SELECT, SHOW VIEW ON ten_database.* TO 'dataxland'@'%'; ``` - `SELECT` đủ để đọc bảng và liệt kê cột, khóa chính, khóa ngoại; `SHOW VIEW` để đọc view. - Không cấp `INSERT`, `UPDATE`, `DELETE`, `FILE`, `PROCESS` hay `SUPER`: DataxLand không cần. - Thay `'%'` bằng địa chỉ máy chủ DataxLand nếu muốn giới hạn nơi đăng nhập (hỏi đội hỗ trợ), và mở tường lửa cho địa chỉ đó. ## 2. Kết nối 1. **Nguồn dữ liệu → Thêm nguồn**, chọn **MySQL / MariaDB**. 2. Điền **Máy chủ**, **Cổng** (mặc định 3306), **Tên database**, **Người dùng**, **Mật khẩu**. 3. **SSL**: - **prefer** (mặc định): mã hóa nếu máy chủ hỗ trợ. - **require**: bắt buộc mã hóa, chấp nhận chứng chỉ tự ký; máy chủ chưa bật TLS thì báo lỗi, không gửi dữ liệu. - **verify-full**: bắt buộc mã hóa và kiểm chứng chỉ do CA công khai cấp, đúng tên máy chủ (Azure, Cloud SQL có chứng chỉ công khai; Amazon RDS dùng CA riêng nên chọn require). - **disable**: không mã hóa, chỉ dùng trong mạng tin cậy. 4. Bấm **Kiểm tra kết nối**, chọn bảng (tùy chọn **Lọc theo ngày**), rồi thêm nguồn. Mật khẩu được mã hóa khi lưu và không hiển thị lại. ## 3. Cách đồng bộ MySQL / MariaDB có **Toàn bộ** và **Tăng dần**. Tăng dần cần một cột con trỏ (DataxLand gợi ý cột như `updated_at`, `modified_at`) và khóa chính để gộp dòng; mỗi lần làm mới đọc dòng có con trỏ mới hơn lần trước (lùi 10 phút cho an toàn). Cột nên có `ON UPDATE CURRENT_TIMESTAMP` để mọi lần sửa đều đổi giá trị. Tăng dần không thấy dòng bị xóa; CDC đọc binlog sẽ có sau. Xem [Cách đồng bộ và lịch làm mới](/vi/docs/concepts/sync-modes). ## Kiểu dữ liệu Dữ liệu vào kho nguyên trạng dưới dạng chữ; từ điển dữ liệu ghi kiểu để bước chuẩn hóa đọc đúng: | Kiểu MySQL | Trong từ điển | Ghi chú | | --- | --- | --- | | `tinyint`, `smallint`, `int`, `bigint` (kể cả `unsigned`), `year` | BIGINT | | | `decimal`, `float`, `double` | DECIMAL | giữ đủ chữ số thập phân | | `bit(1)` | BOOLEAN | `true`/`false`; `bit(n)` khác đọc ra số | | `date` | DATE | ngày `0000-00-00` thành rỗng | | `datetime`, `timestamp` | DATETIME | `timestamp` đọc theo giờ Việt Nam | | `time`, `char`, `varchar`, `text`, `enum`, `set`, `json` | VARCHAR | `time` dạng `HH:MM:SS` | | `blob`, `binary` | (bỏ trống) | dữ liệu nhị phân không dùng | ## Si điều tra bằng SQL Như PostgreSQL, Si được chạy SQL chỉ đọc trên nguồn khi điều tra, trong giới hạn số câu và chi phí (ước tính bằng `EXPLAIN`); câu vượt giới hạn chờ người kỹ thuật xác nhận. ## Liên quan - [PostgreSQL](/vi/docs/sources/postgres) - [SQL Server / Azure SQL](/vi/docs/sources/mssql) - [Bảo mật và quyền riêng tư](/vi/docs/security-privacy) --- # PostgreSQL > Nối database PostgreSQL bằng người dùng chỉ đọc, chọn bảng, nạp toàn bộ, tăng dần hoặc CDC; điều kiện bật CDC trên Postgres tự quản, RDS, Cloud SQL, Neon, Supabase. PostgreSQL cần gói Khởi đầu trở lên. Dữ liệu được chép về kho riêng của workspace qua kết nối chỉ đọc; DataxLand không ghi vào database của bạn. ## 1. Chuẩn bị người dùng Tạo một người dùng riêng cho DataxLand, chỉ có quyền đọc: ```sql CREATE ROLE dataxland LOGIN PASSWORD ''; GRANT USAGE ON SCHEMA public TO dataxland; GRANT SELECT ON ALL TABLES IN SCHEMA public TO dataxland; ``` Nếu database chỉ mở cho IP nhất định, mở cho địa chỉ máy chủ DataxLand (hỏi đội hỗ trợ). ## 2. Kết nối 1. **Nguồn dữ liệu → Thêm nguồn**, chọn **PostgreSQL**. 2. Điền **Máy chủ**, **Cổng** (mặc định 5432), **Tên database**, **Schema** (mặc định `public`), **Người dùng**, **Mật khẩu**. **SSL**: Mặc định, prefer, require hoặc disable; dùng require khi database ở ngoài mạng nội bộ. 3. Bấm **Kiểm tra kết nối**. 4. Ở **Chọn bảng cần đọc**, đánh dấu bảng. Tùy chọn **Lọc theo ngày**: chọn cột ngày, **Từ ngày**, **Đến ngày** để chỉ nạp một khoảng. 5. Thêm nguồn. Mật khẩu được mã hóa khi lưu và không hiển thị lại. Sửa sau này ở thẻ **Kết nối và bảng → Sửa kết nối**; thay đổi có hiệu lực ở lần làm mới kế tiếp. ## 3. Cách đồng bộ PostgreSQL hỗ trợ cả ba cách: **Toàn bộ**, **Tăng dần** (cần cột con trỏ như `updated_at` và khóa chính) và **CDC (đọc log)**. Xem [Cách đồng bộ và lịch làm mới](/vi/docs/concepts/sync-modes). ## CDC CDC đọc nhật ký thay đổi (WAL) qua logical replication nên thấy cả dòng bị sửa và bị xóa, và cho phép làm mới tới mỗi 15 phút. DataxLand tạo một replication slot `pgoutput` riêng cho nguồn; lần đồng bộ đầu nạp toàn bộ. Bấm **Kiểm tra điều kiện CDC** ở trang nguồn. Mỗi mục ghi **Đạt** hoặc **Chưa đạt**: | Điều kiện | Cách đạt | | --- | --- | | `wal_level = logical` | Đặt `wal_level = logical` rồi khởi động lại Postgres. RDS, Aurora: `rds.logical_replication = 1`. Cloud SQL: `cloudsql.logical_decoding = on`. Neon, Supabase: bật Logical Replication trong cài đặt dự án | | Quyền REPLICATION | `ALTER ROLE dataxland WITH REPLICATION;` (RDS: `GRANT rds_replication TO dataxland;`) | | Còn chỗ cho replication slot | Tăng `max_replication_slots` hoặc xóa slot không dùng | | Bảng có khóa chính hoặc REPLICA IDENTITY FULL | Thêm khóa chính, hoặc `ALTER TABLE ten_bang REPLICA IDENTITY FULL;` | | Tạo được publication | Người dùng sở hữu bảng và có quyền CREATE trên database, hoặc quản trị viên tạo sẵn: `CREATE PUBLICATION ten_publication FOR TABLE bang_a, bang_b;` | ### Theo dõi độ trễ Bấm **Xem độ trễ CDC** để xem lượng WAL slot đang giữ. Khi slot giữ hơn 1 GB, trang báo **Slot CDC đang giữ hơn 1 GB WAL**: hãy làm mới thường hơn. Slot không được đồng bộ 7 ngày sẽ bị DataxLand xóa để không làm đầy ổ đĩa của database (có cảnh báo từ ngày thứ 5); lần sau nguồn nạp toàn bộ lại. ## Si điều tra bằng SQL Với PostgreSQL, Si được chạy SQL chỉ đọc trên nguồn khi điều tra, trong giới hạn số câu và chi phí. Bạn cũng tự chạy được ở **Duyệt đề xuất → Nâng cao: chạy SQL trên nguồn** (nút **Ước tính**, **Chạy trên database**). ## Liên quan - [Kết nối dữ liệu](/vi/docs/connect-data) - [BigQuery](/vi/docs/sources/bigquery) - [Bảo mật và quyền riêng tư](/vi/docs/security-privacy) --- # REST API tùy biến > Nối phần mềm bất kỳ có REST API trả JSON (POS, CRM, kho, ERP nội bộ) bằng cách khai báo địa chỉ gốc, xác thực, endpoint và phân trang, rồi thử gọi trước khi thêm. Dùng connector này khi phần mềm của bạn không có trong [thư viện](/vi/docs/sources/connector-library) nhưng có REST API trả JSON. Cần gói Khởi đầu trở lên. ## 1. Địa chỉ và xác thực - **Địa chỉ gốc API**: bắt đầu bằng `https://`. DataxLand chỉ gửi yêu cầu tới đúng host của địa chỉ này. - **Xác thực**: | Kiểu | Bạn điền | | --- | --- | | Không xác thực | — | | API key | Khóa, **Tên header hoặc tham số**, **Gửi trong** header hoặc query | | Bearer token | Token | | Basic (tên đăng nhập, mật khẩu) | Tên đăng nhập, mật khẩu | | OAuth2 client credentials | Token URL, Client ID, Client secret, Scope | - **Header thêm** (tối đa 30): header cố định API cần. Không đặt bí mật ở đây; bí mật thuộc ô xác thực, được mã hóa khi lưu. ## 2. Endpoint Mỗi endpoint (1–20) thành một bảng: | Ô | Ví dụ | | --- | --- | | Tên bảng | `orders` | | Đường dẫn | `/v1/orders` | | Tham số | `updated_from` = `{{ start_date }}` | | Đường dẫn tới danh sách bản ghi | `data.items` | | Khóa chính | `id` | | Phân trang | xem bên dưới | | Số trang tối đa | mặc định 1000 | **Phân trang**: Không phân trang, Theo số trang, Theo vị trí (limit/offset), Theo con trỏ, Theo link trang sau. Ô chung: **Lấy dữ liệu từ ngày** (giá trị của `{{ start_date }}`) và **Thời gian chờ mỗi lần gọi (giây)**, mặc định 30. ## 3. Thử gọi Bấm **Thử gọi**: DataxLand gọi endpoint, hiện tối đa 20 bản ghi và **Cột suy ra**, thông tin cá nhân đã được che. Sửa đường dẫn danh sách hay phân trang tới khi đúng, rồi thêm nguồn. ## Giới hạn hiện tại - Gọi bằng GET, POST hoặc GraphQL; phản hồi dạng JSON. - Mỗi lần làm mới đọc lại toàn bộ (lọc từ **Lấy dữ liệu từ ngày**). ## Liên quan - [Thư viện connector](/vi/docs/sources/connector-library) - [Kết nối dữ liệu](/vi/docs/connect-data) - [Che thông tin cá nhân](/vi/docs/review/pii) --- # Shopee > Kết nối shop Shopee bằng nút Kết nối với Shopee (OAuth) — không dán mật khẩu — để đọc đơn hàng, quyết toán, trả hàng, sản phẩm và quảng cáo. Kết nối Shopee cần gói Khởi đầu trở lên. Bạn cấp quyền trên trang của Shopee; DataxLand không bao giờ thấy mật khẩu shop. ## Kết nối 1. Khi tạo workspace: nhập **Tên workspace** trước. Với workspace đã có: **Nguồn dữ liệu → Thêm nguồn**. 2. Bấm **Kết nối với Shopee**. Nếu chọn nhiều nguồn cùng lúc, đánh dấu **Thêm vào danh sách, kết nối sau cùng các connector khác**; sàn được kết nối sau cùng. 3. Trên trang Shopee, đăng nhập tài khoản chủ shop và đồng ý cấp quyền. 4. Shopee chuyển bạn về DataxLand: **Đã kết nối nguồn Shopee**. Nếu còn sàn khác trong hàng chờ, bấm **Kết nối tiếp với …** hoặc **Bỏ qua**. Mặc định đọc **90 ngày gần nhất**; đổi bằng **Lấy dữ liệu từ ngày**. Các lần sau đọc tăng dần theo thời điểm cập nhật đơn. ## Dữ liệu được đọc | Bảng | Nội dung | | --- | --- | | `orders` | Đơn hàng, trạng thái, thời điểm | | `order_items` | Dòng hàng của đơn | | `escrow_details` | Quyết toán: phí sàn, phí thanh toán, voucher, tiền về | | `returns` | Trả hàng, hoàn tiền | | `products` | Sản phẩm | | `ads_daily` | Chi phí quảng cáo Shopee theo ngày | Tên, số điện thoại, địa chỉ người mua được che và băm như mọi nguồn khác. ## Khi không kết nối được - Nút ghi **Chưa cấu hình khóa ứng dụng**: kết nối Shopee chưa mở trên máy chủ này. Tạm thời, xuất báo cáo từ Shopee ra Excel và dùng [File Excel](/vi/docs/sources/excel). - Thấy **Chưa kết nối được với sàn** khi quay về: bạn đã hủy hoặc phiên cấp quyền hết hạn; bấm kết nối lại. ## Liên quan - [TikTok Shop](/vi/docs/sources/tiktok-shop) · [Lazada](/vi/docs/sources/lazada) - [Trang connector Shopee](/vi/connectors/shopee) - [Cách đồng bộ và lịch làm mới](/vi/docs/concepts/sync-modes) --- # TikTok Shop > Kết nối TikTok Shop bằng nút Kết nối với TikTok Shop (OAuth) để đọc đơn hàng, sao kê thanh toán, giao dịch sao kê, trả hàng và sản phẩm. Kết nối TikTok Shop cần gói Khởi đầu trở lên. Bạn cấp quyền trên trang của TikTok Shop; DataxLand không thấy mật khẩu. ## Kết nối 1. Khi tạo workspace: nhập **Tên workspace** trước. Với workspace đã có: **Nguồn dữ liệu → Thêm nguồn**. 2. Bấm **Kết nối với TikTok Shop** (hoặc đánh dấu **Thêm vào danh sách, kết nối sau cùng các connector khác** khi chọn nhiều nguồn). 3. Trên trang TikTok Shop, đăng nhập tài khoản người bán và đồng ý cấp quyền. 4. Quay về DataxLand: **Đã kết nối nguồn TikTok Shop**. Mặc định đọc **90 ngày gần nhất** (**Lấy dữ liệu từ ngày** để đổi); các lần sau đọc tăng dần. ## Dữ liệu được đọc | Bảng | Nội dung | | --- | --- | | `orders` | Đơn hàng | | `order_items` | Dòng hàng | | `statements` | Sao kê thanh toán theo kỳ | | `statement_transactions` | Giao dịch trong sao kê: phí, hoa hồng, điều chỉnh | | `returns` | Trả hàng, hoàn tiền | | `products` | Sản phẩm | Chi phí quảng cáo TikTok không nằm trong connector này; thêm connector quảng cáo từ [thư viện](/vi/docs/sources/connector-library) nếu cần. ## Khi không kết nối được - **Chưa cấu hình khóa ứng dụng**: kết nối TikTok Shop chưa mở trên máy chủ này. Tạm thời dùng file xuất từ Seller Center với [File Excel](/vi/docs/sources/excel). - **Chưa kết nối được với sàn**: bạn đã hủy hoặc phiên cấp quyền hết hạn; thử lại. ## Liên quan - [Shopee](/vi/docs/sources/shopee) · [Lazada](/vi/docs/sources/lazada) - [Kết nối dữ liệu](/vi/docs/connect-data) --- # Chế độ cách ly mạng > Chạy DataxLand trong mạng không ra Internet - danh sách máy chủ được gọi, NetworkPolicy bắt buộc, model AI nội bộ, SMTP nội bộ, tính năng bị tắt, nguồn dữ liệu còn dùng được và cách chép ảnh vào registry nội bộ. Chế độ cách ly mạng dành cho bản cài không được gọi ra Internet. Khi bật, DataxLand chỉ gọi tới các máy chủ bạn liệt kê, tự tắt những tính năng cần máy chủ bên ngoài và cho biết lý do. DataxLand không có telemetry gửi về DataxLand, kể cả khi không cách ly. Giấy phép được kiểm offline. ## 1. Bật chế độ và khai báo máy chủ được gọi ```yaml airgapped: enabled: true egressAllow: - llm.corp.example # tên chính xác - smtp.corp.example - "*.db.corp.example" # mọi máy chủ con của db.corp.example - 10.20.0.0/16 # dải địa chỉ (CIDR) ``` Mỗi mục là một trong ba dạng: | Dạng | Ví dụ | Khớp | | --- | --- | --- | | Tên chính xác | `llm.corp.example` | Đúng tên đó | | `*.hậu-tố` | `*.db.corp.example` | `pg.db.corp.example`, `a.b.db.corp.example`; không khớp chính `db.corp.example` | | CIDR hoặc IP | `10.20.0.0/16`, `10.20.1.5` | Máy chủ phân giải ra địa chỉ trong dải | - Địa chỉ metadata của đám mây và link-local (`169.254.0.0/16`) **luôn bị chặn**, kể cả khi nằm trong danh sách. - Model AI và SMTP được kiểm theo **tên** trong cấu hình lúc khởi động. Ghi tên máy chủ của chúng (hoặc IP nếu cấu hình bằng IP), không chỉ dải CIDR. - Không cách ly, danh sách này vẫn có ích: theo mặc định DataxLand không cho kết nối tới địa chỉ nội bộ (chống SSRF), nên database nguồn trong mạng của bạn phải có trong `egressAllow` thì mới kết nối được. ## 2. Chặn ở mức mạng (bắt buộc) Kiểm tra trong ứng dụng là lớp thứ hai. Tiến trình con của connector không mang chính sách của ứng dụng, nên lớp chính phải là NetworkPolicy của chart và tường lửa của bạn: ```yaml networkPolicy: enabled: true egress: restrict: true dnsNamespace: kube-system allowCIDRs: [10.0.0.0/16, 10.20.0.0/16] # Postgres, object storage, model AI, SMTP, database nguồn allowPorts: [5432, 443, 587, 1433, 3306, 8000] ``` Helm cảnh báo khi `airgapped.enabled` bật mà `networkPolicy.egress.restrict` tắt. Cần CNI hỗ trợ NetworkPolicy. ## 3. Model AI nội bộ Danh mục model mặc định trong ảnh gọi API của nhà cung cấp bên ngoài. Khi cách ly, mỗi route phải trỏ tới model có máy chủ nằm trong `egressAllow`; nếu không, ứng dụng báo lỗi cấu hình ngay lúc khởi động, nêu rõ route và máy chủ sai. Đặt danh mục riêng bằng `llm.modelsYaml`, với model kiểu `openai_compat` (vLLM, Ollama, LM Studio, TGI): ```yaml llm: modelsYaml: | models: internal-qwen: provider: openai_compat base_url: http://llm.corp.example:8000/v1 # vLLM model: Qwen/Qwen3-32B api_key_env: INTERNAL_LLM_API_KEY # khóa trong Secret dataxland-env; null nếu không cần capabilities: [structured_output, tool_use] region: local internal-ollama: provider: openai_compat base_url: http://ollama.corp.example:11434/v1 # Ollama model: qwen3:32b api_key_env: null capabilities: [structured_output, tool_use] region: local routes: {copilot: internal-qwen, agent: internal-qwen} ``` - Route `copilot` (Si phân tích ngữ cảnh) cần model có `structured_output`; route `agent` (Si hỏi đáp) cần `tool_use`. - Chỉ khai báo khả năng mà model thực sự làm tốt. Chất lượng câu trả lời của Si phụ thuộc model bạn chọn; hãy thử với dữ liệu của mình trước khi đưa vào dùng. - `llm.copilotModel` và `llm.agentModel` chọn model theo tên trong danh mục mà không phải sửa `routes`. ## 4. Email qua SMTP nội bộ ```yaml deployment: extraEnv: DX_SMTP_HOST: smtp.corp.example DX_SMTP_PORT: "587" DX_SMTP_USER: dataxland DX_SMTP_FROM: dataxland@corp.example ``` Mật khẩu đặt ở khóa `DX_SMTP_PASSWORD` của Secret. Khi cách ly, máy chủ SMTP không có trong `egressAllow` thì email bị tắt. ## 5. Tính năng bị tắt Khi cách ly, các tính năng sau tự tắt nếu máy chủ chúng cần không có trong `egressAllow`: | Tính năng | Máy chủ cần | | --- | --- | | Đăng nhập Google | `accounts.google.com`, `oauth2.googleapis.com` | | CAPTCHA Turnstile | `challenges.cloudflare.com` | | Kết nối sàn Shopee, TikTok Shop, Lazada | Máy chủ API và đăng nhập của sàn | | Kênh Telegram | `api.telegram.org` | | Kênh Slack | `slack.com`, `hooks.slack.com` | | Kênh Microsoft Teams | `login.microsoftonline.com`, `login.botframework.com`, `smba.trafficmanager.net` | | Google Sheets | `sheets.googleapis.com`, `oauth2.googleapis.com` | | Email | Máy chủ SMTP của bạn | | Gửi trace (OTLP) | Máy chủ nhận trace | Mọi kết nối OAuth (sàn TMĐT và thư viện connector) **tắt mặc định** khi cách ly. Muốn bật, liệt kê chúng trong `DX_OAUTH_PROVIDERS` ở `deployment.extraEnv`; sàn vẫn bị tắt nếu máy chủ của sàn không có trong `egressAllow`. Xem danh sách thực tế của bản cài ở **Quản trị → Vận hành**, mục **Triển khai và giấy phép**: máy chủ được gọi ra và từng tính năng bị tắt kèm lý do. Hoặc: ```bash kubectl -n dataxland exec deploy/dataxland-worker -- python -m pipelines.cli license-status ``` ## 6. Nguồn dữ liệu Mặc định khi cách ly chỉ còn các nguồn có sẵn trong ảnh và nối tới máy chủ do bạn nhập: **Excel**, **PostgreSQL**, **MySQL**, **SQL Server**. Máy chủ database phải có trong `egressAllow` và được NetworkPolicy cho phép. BigQuery, thư viện connector và các runtime Singer, dlt, Airbyte chỉ bật khi đặt `DX_SOURCE_CONNECTORS` trong `deployment.extraEnv`, và từng kết nối vẫn bị chặn nếu máy chủ không được phép. Connector Airbyte kiểu cài từ PyPI lúc chạy, hoặc kiểu manifest chưa có trong bộ đệm, không chạy được khi cách ly. ## 7. Chép ảnh vào registry nội bộ Các thành phần sau **đã nằm trong ảnh `api`**, không phải tải lúc chạy: mô hình embedding, extension DuckDB, runtime connector Singer, dlt và Airbyte. Bạn chỉ cần chép ảnh. Trên máy có Internet và có [skopeo](https://github.com/containers/skopeo), từ bộ mã nguồn DataxLand cung cấp cùng bản phát hành: ```bash # Xem danh sách ảnh python -m tools.mirror_images list --tag --owner # Cách 1: registry nội bộ nối được từ máy này python -m tools.mirror_images mirror --tag --owner --to registry.corp.example/dataxland # Cách 2: đóng gói để mang vào mạng kín python -m tools.mirror_images bundle --tag --owner --out ./dx-bundle ``` - Danh sách gồm ảnh `api` (dùng chung cho `worker`, `mcp` và các Job), `web`, `site`, cùng các ảnh phụ trong chart (Postgres và MinIO dùng thử, s3proxy). `--with-build` thêm các ảnh nền nếu bạn muốn tự build ảnh trong mạng kín. - Ảnh được chép với cả hai kiến trúc amd64 và arm64. `--dry-run` chỉ in lệnh `skopeo`. - `bundle` ghi mỗi ảnh một tệp `oci-archive`, kèm `images.txt` (tệp, ảnh gốc, tên đích) và `SHA256SUMS`. Trong mạng kín, kiểm `SHA256SUMS` rồi nạp từng tệp: ```bash skopeo copy oci-archive:.tar docker://registry.corp.example/dataxland/: ``` Sau đó trỏ chart vào registry nội bộ: ```yaml image: registry: registry.corp.example repositoryPrefix: dataxland ``` Nếu dùng s3proxy hoặc Postgres, MinIO dùng thử, đặt thêm `s3proxy.image`, `postgres.bundled.image`, `minio.image` theo tên đích trong `images.txt`. ## Liên quan - [Cài bằng Helm](/vi/docs/self-host/helm) - [Yêu cầu và cỡ máy](/vi/docs/self-host/requirements) - [Giấy phép](/vi/docs/self-host/license) --- # Cài bằng Helm > Cài DataxLand lên Kubernetes bằng Helm chart, gồm Secret bí mật, Secret giấy phép, values tối thiểu cho production, kiểm tra sau khi cài, bản dùng thử với Postgres và MinIO trong cụm, External Secrets, NetworkPolicy và ServiceMonitor. Trang này dùng tên bản cài `dataxland`, namespace `dataxland` và tên miền `dataxland.corp.example`. Thay bằng giá trị của bạn. Trước khi bắt đầu, cần có: hạ tầng theo [Yêu cầu và cỡ máy](/vi/docs/self-host/requirements), Helm 3, `kubectl` trỏ vào cụm, và từ DataxLand: chart, tên kho ảnh, quyền kéo ảnh (hoặc [gói ảnh offline](/vi/docs/self-host/airgapped#7-chép-ảnh-vào-registry-nội-bộ)) và tệp giấy phép `license.json`. ## 1. Namespace ```bash kubectl create namespace dataxland ``` Mỗi namespace chỉ chứa **một** bản cài: Service của `api` luôn tên là `api` (ảnh `web` gọi sẵn địa chỉ `http://api:8000`). Nếu kho ảnh cần đăng nhập, tạo Secret kéo ảnh rồi khai báo ở `imagePullSecrets`: ```bash kubectl -n dataxland create secret docker-registry dataxland-pull \ --docker-server=ghcr.io --docker-username= --docker-password= ``` ## 2. Secret bí mật Chart không chứa giá trị bí mật nào. Tạo một Secret, mỗi khóa trùng tên một biến môi trường: | Khóa | Bắt buộc | Nội dung | | --- | --- | --- | | `DX_POSTGRES_URL` | có | Chuỗi kết nối database `dx`, ví dụ `postgresql://dx:@pg.corp.example:5432/dx?sslmode=require` | | `DX_DUCKLAKE_CATALOG_PASSWORD` | có | Mật khẩu của user Postgres (dùng cho database `dx_lake`) | | `DX_SESSION_SECRET` | có | Chuỗi ngẫu nhiên, ký phiên đăng nhập | | `DX_SECRET_KEY` | có | Chuỗi ngẫu nhiên, mã hóa bí mật đã lưu (mật khẩu nguồn, token) | | `DX_DELEGATION_SIGNING_KEY` | có | Chuỗi ngẫu nhiên, ký token ủy quyền ngắn hạn giữa các dịch vụ | | `DX_BACKUP_ENCRYPTION_KEY` | có | 32 byte, base64 url-safe, mã hóa bản sao lưu | | `DX_DUCKLAKE_S3_KEY_ID`, `DX_DUCKLAKE_S3_SECRET` | có | Khóa object storage | | `DX_SMTP_PASSWORD` | không | Mật khẩu SMTP | | `DX_BACKUP_S3_KEY_ID`, `DX_BACKUP_S3_SECRET` | không | Khóa riêng cho bucket sao lưu, nếu khác khóa kho | | `DX_METRICS_TOKEN` | không | Bắt buộc token khi đọc `/metrics` | | Khóa API model | tùy model | Tên biến theo `api_key_env` của model. Danh mục mặc định hiện dùng `DEEPSEEK_API_KEY` | ```bash kubectl -n dataxland create secret generic dataxland-env \ --from-literal=DX_POSTGRES_URL='postgresql://dx:@pg.corp.example:5432/dx?sslmode=require' \ --from-literal=DX_DUCKLAKE_CATALOG_PASSWORD='' \ --from-literal=DX_SESSION_SECRET="$(openssl rand -hex 32)" \ --from-literal=DX_SECRET_KEY="$(openssl rand -hex 32)" \ --from-literal=DX_DELEGATION_SIGNING_KEY="$(openssl rand -hex 32)" \ --from-literal=DX_BACKUP_ENCRYPTION_KEY="$(openssl rand -base64 32 | tr '+/' '-_')" \ --from-literal=DX_DUCKLAKE_S3_KEY_ID='' \ --from-literal=DX_DUCKLAKE_S3_SECRET='' ``` Mật khẩu Postgres có ký tự đặc biệt thì phải mã hóa URL trong `DX_POSTGRES_URL`. **Lưu ngay `DX_SECRET_KEY` và `DX_BACKUP_ENCRYPTION_KEY` ra hai nơi** (kho bí mật của công ty và một bản ngoại tuyến). Mất `DX_SECRET_KEY` thì phải nối lại mọi nguồn dữ liệu; mất `DX_BACKUP_ENCRYPTION_KEY` thì mọi bản sao lưu không giải mã được. ## 3. Secret giấy phép ```bash kubectl -n dataxland create secret generic dataxland-license --from-file=license.json=./license.json ``` Chưa có giấy phép thì bản cài vẫn chạy nhưng ở chế độ chỉ đọc. Xem [Giấy phép](/vi/docs/self-host/license). ## 4. Values cho production Tệp `values-prod.yaml` tối thiểu (ví dụ trên AWS): ```yaml image: repositoryPrefix: imagePullSecrets: - name: dataxland-pull deployment: publicUrl: https://dataxland.corp.example superAdmins: [admin@corp.example] extraEnv: DX_SMTP_HOST: smtp.corp.example DX_SMTP_PORT: "587" DX_SMTP_USER: dataxland DX_SMTP_FROM: dataxland@corp.example license: existingSecret: dataxland-license secrets: existingSecret: dataxland-env postgres: external: host: pg.corp.example database: dx catalogDatabase: dx_lake user: dx objectStorage: endpoint: s3.ap-southeast-1.amazonaws.com region: ap-southeast-1 urlStyle: vhost lakeBucket: dx-lake tenantKeys: "off" backup: bucket: dx-backups persistence: storageClass: efs-rwx size: 100Gi ingress: className: nginx host: dataxland.corp.example annotations: cert-manager.io/cluster-issuer: letsencrypt ``` Những khóa hay cần đổi: | Khóa | Ý nghĩa | | --- | --- | | `deployment.publicUrl` | Địa chỉ người dùng mở, bắt buộc | | `deployment.superAdmins` | Email quản trị toàn bản cài | | `deployment.signupMode` | `invite` (mặc định), `approval` hoặc `open` | | `deployment.timezone` | Múi giờ cho ngày nghiệp vụ và giờ sao lưu, mặc định `Asia/Ho_Chi_Minh` | | `deployment.extraEnv` | Biến môi trường thêm cho `api`, `worker`, `mcp` (SMTP, kênh thông báo) | | `image.registry`, `image.repositoryPrefix`, `image.tag` | Kho ảnh; `image.tag` trống thì dùng phiên bản của chart | | `image.digests` | Ghim ảnh theo digest, ví dụ `{api: sha256:..., web: sha256:...}` | | `objectStorage.lakePrefix` | Tiền tố trong bucket kho, khi dùng chung bucket | | `ingress.tls.secretName` | Secret chứa chứng chỉ; trống thì dùng `dataxland-tls` (cert-manager tạo) | | `ingress.mcp.enabled`, `ingress.mcp.host` | Mở máy chủ MCP ra ngoài, ví dụ `mcp.dataxland.corp.example` | | `ingress.api.enabled`, `ingress.api.host` | Mở thẳng `/v1` của api, chỉ khi cần callback OAuth hoặc webhook | | `api.autoscaling.enabled`, `web.autoscaling.enabled` | Bật HPA | | `mcp.enabled` | Tắt máy chủ MCP nếu không dùng | Object storage trên GCP, Azure hay on-prem: xem bảng ở [Yêu cầu và cỡ máy](/vi/docs/self-host/requirements#object-storage-theo-đám-mây). ## 5. Cài ```bash helm install dataxland <đường dẫn chart> -n dataxland -f values-prod.yaml kubectl -n dataxland get pods -w ``` `<đường dẫn chart>` là thư mục hoặc tệp `.tgz` của chart DataxLand cung cấp cùng bản phát hành. Lần cài đầu, các thành phần tự tạo schema Postgres; từ lần nâng cấp sau, Job `migrate` làm việc này trước khi cuộn bản mới. Helm in ghi chú sau khi cài, kèm cảnh báo nếu thiếu giấy phép, đang dùng Postgres hoặc MinIO trong cụm, hoặc Secret do chart tự tạo. ## 6. Kiểm tra và đăng nhập ```bash kubectl -n dataxland port-forward svc/api 8000:8000 curl -s http://localhost:8000/readyz ``` `/readyz` kiểm Postgres, catalog và object storage. Khi trả thành công: 1. Mở `https://dataxland.corp.example`. 2. **Đăng ký** bằng email trong `deployment.superAdmins`. Email này không cần mã mời và bắt buộc bật xác thực hai lớp. 3. Vào **Quản trị → Vận hành**, mục **Triển khai và giấy phép**: xem trạng thái giấy phép, mức dùng và chế độ cách ly. 4. Tạo workspace đầu tiên rồi mời người dùng. Xem trạng thái giấy phép từ dòng lệnh: ```bash kubectl -n dataxland exec deploy/dataxland-worker -- python -m pipelines.cli license-status ``` ## Dùng thử với Postgres và MinIO trong cụm Để thử trên một cụm nhỏ, chart có thể chạy Postgres và MinIO ngay trong cụm. Hai thành phần này **chỉ để dùng thử**: một bản, không sao lưu, không HA. ```yaml # values-trial.yaml deployment: publicUrl: http://localhost:3000 superAdmins: [admin@corp.example] license: existingSecret: dataxland-license postgres: bundled: enabled: true minio: bundled: true objectStorage: tenantKeys: minio persistence: accessMode: ReadWriteOnce size: 10Gi api: replicas: 1 web: replicas: 1 ingress: enabled: false ``` ```bash helm install dataxland <đường dẫn chart> -n dataxland -f values-trial.yaml kubectl -n dataxland port-forward svc/dataxland-web 3000:3000 ``` Không đặt `secrets.existingSecret` thì chart tự tạo Secret `dataxland-env` với khóa ngẫu nhiên, giữ qua các lần nâng cấp. Bản dùng thử vẫn cần tệp giấy phép; không có thì bản cài chỉ đọc. ## Bí mật từ External Secrets Operator Nếu bí mật nằm trong kho bí mật (AWS Secrets Manager, Google Secret Manager, Azure Key Vault, Vault) và cụm đã có External Secrets Operator, chart tạo `ExternalSecret` thay cho Secret tạo tay. Đích vẫn là Secret `dataxland-env`. ```yaml secrets: existingSecret: "" externalSecret: enabled: true secretStoreRef: {name: cloud-secrets, kind: ClusterSecretStore} refreshInterval: 1h data: DX_SECRET_KEY: dataxland/prod/secret-key DX_POSTGRES_URL: {key: dataxland-app, property: DX_POSTGRES_URL} ``` Mỗi khóa trong `data` là tên biến; giá trị là `remoteKey` trong kho, hoặc một `remoteRef` đầy đủ (`key`, `property`) khi nhiều biến nằm trong một bí mật JSON. Liệt kê đủ các khóa bắt buộc ở mục 2. ## NetworkPolicy Cần CNI hỗ trợ NetworkPolicy. Bật: ```yaml networkPolicy: enabled: true ingressControllerNamespace: ingress-nginx ingressControllerLabels: {app.kubernetes.io/name: ingress-nginx} monitoringNamespace: monitoring ``` Chart chặn mọi kết nối vào, rồi chỉ cho: ingress controller vào `web` và `mcp` (và `api` nếu bật `ingress.api`), các pod của bản cài gọi nhau, Prometheus trong `monitoringNamespace` đọc cổng chỉ số 9464 đến 9466. Giới hạn kết nối ra (bắt buộc khi cách ly mạng): ```yaml networkPolicy: enabled: true egress: restrict: true dnsNamespace: kube-system allowCIDRs: [10.0.0.0/16] allowPorts: [5432, 443, 587] ``` Khi `restrict: true`, pod chỉ được gọi DNS, các pod cùng bản cài và các dải trong `allowCIDRs` (Postgres, object storage, model AI, SMTP, database nguồn). `allowPorts` trống nghĩa là mọi cổng tới các dải đó. ## ServiceMonitor Với Prometheus Operator: ```yaml serviceMonitor: enabled: true interval: 30s labels: {release: prometheus} ``` Chart thu `/metrics` của `api` (cổng 9464), `worker` (9465), `mcp` (9466). Nếu đặt `DX_METRICS_TOKEN`, ServiceMonitor của chart không tự gửi token; thêm cấu hình xác thực cho Prometheus của bạn. Bộ luật cảnh báo Prometheus đi kèm bản phát hành; hãy nạp thêm cảnh báo giấy phép sắp hết hạn (xem [Giấy phép](/vi/docs/self-host/license#theo-dõi-hạn)). ## Liên quan - [Chế độ cách ly mạng](/vi/docs/self-host/airgapped) - [Nâng cấp và sao lưu](/vi/docs/self-host/upgrade-backup) - [Giấy phép](/vi/docs/self-host/license) --- # Tự host (gói Doanh nghiệp) > Chạy DataxLand trong hạ tầng Kubernetes của doanh nghiệp bằng Helm chart, với giấy phép offline và chế độ cách ly mạng; khi nào nên chọn, gồm những gì, khác bản cloud ở đâu và giới hạn đã biết. Gói Doanh nghiệp có thể chạy DataxLand **trong hạ tầng của bạn**: dữ liệu, kho và bản sao lưu nằm trong tài khoản đám mây hoặc trung tâm dữ liệu của bạn, model AI có thể là model nội bộ, và bản cài có thể không gọi ra Internet. ## Khi nào nên tự host - Quy định nội bộ hoặc pháp lý yêu cầu dữ liệu không rời mạng của doanh nghiệp. - Bạn cần dùng model AI nội bộ thay cho model của nhà cung cấp bên ngoài. - Database nguồn chỉ truy cập được trong mạng nội bộ và không mở ra ngoài. - Bạn có đội hạ tầng vận hành Kubernetes, Postgres và object storage. Nếu không có các ràng buộc trên, [DataxLand Cloud](/vi/pricing) ít việc vận hành hơn: sao lưu, nâng cấp và giám sát do DataxLand làm. ## Mô hình: một bản cài cho một khách - Một bản cài phục vụ **một tổ chức**. Trong bản cài có thể có nhiều workspace và nhiều người dùng, trong giới hạn của giấy phép. - Bản tự host chạy **cùng mã và cùng ảnh** với DataxLand Cloud. Khác nhau chỉ ở cấu hình và tệp giấy phép, nên tính năng và bản sửa lỗi đến cùng lúc. - Cài bằng **Helm chart** lên Kubernetes bất kỳ (1.27 trở lên). Có thêm **module Terraform tham khảo** cho AWS, GCP và Azure. ## Thành phần | Thành phần | Việc | Số bản mặc định | | --- | --- | --- | | `web` | Giao diện người dùng | 2 | | `api` | API, dashboard, hỏi Si | 2 | | `mcp` | Máy chủ MCP cho agent bên ngoài (tắt được) | 1 | | `worker` | Nạp và build dữ liệu, lịch làm mới, sao lưu, bảo trì kho | luôn 1 | | Job `migrate` | Nâng schema Postgres trước mỗi lần nâng cấp | chạy một lần | | CronJob sao lưu | Tùy chọn, khi bạn muốn Kubernetes quản lịch sao lưu | tắt | Bên ngoài cụm, bạn cung cấp: - **Postgres 16** có quản lý: metadata của ứng dụng và catalog của kho dữ liệu. - **Object storage tương thích S3**: kho dữ liệu (Parquet) và bản sao lưu. - **Ổ dùng chung** (PersistentVolumeClaim): tệp tải lên, cấu hình workspace, bí mật đã mã hóa, thư mục làm việc khi build. Chi tiết ở [Yêu cầu và cỡ máy](/vi/docs/self-host/requirements). ## Khác gì bản cloud | | DataxLand Cloud | Tự host | | --- | --- | --- | | Hạ tầng, sao lưu, nâng cấp | DataxLand vận hành | Đội hạ tầng của bạn | | Đăng ký tài khoản | Theo trang đăng ký | Mặc định chỉ qua lời mời; quản trị toàn bản cài khai báo bằng email | | Gói | Theo đăng ký | Gói Doanh nghiệp, mọi tính năng | | Bản quyền | Thanh toán theo gói | [Tệp giấy phép offline](/vi/docs/self-host/license), không gọi về DataxLand | | Model AI | Model do DataxLand chọn | Danh mục mặc định (gọi API của nhà cung cấp model), hoặc model nội bộ của bạn | | Gọi ra Internet | Có | Tùy bạn; có [chế độ cách ly mạng](/vi/docs/self-host/airgapped) | | Gửi dữ liệu về DataxLand | Không áp dụng | Không có gì được gửi về DataxLand | ## Giới hạn đã biết Đọc kỹ trước khi lên kế hoạch: - **Ổ dùng chung phải là ReadWriteMany khi có nhiều nút.** `api`, `mcp` và `worker` đọc ghi cùng một thư mục. Trên đám mây là EFS (AWS), Filestore (GCP), Azure Files (Azure); on-prem là NFS hoặc CephFS. Chỉ khi cả bản cài chạy trên một nút thì ReadWriteOnce mới đủ. Hiệu năng của NFS với thư mục build là phụ thuộc vận hành lớn nhất. - **`worker` chỉ chạy một bản.** Chart cố định một bản và cập nhật kiểu thay thế (Recreate): trong lúc nâng cấp, việc nền (build, lịch làm mới, sao lưu) dừng vài phút. Dashboard và hỏi Si vẫn chạy. - **Một khóa object storage cho cả bucket trên đám mây.** Trên S3, GCS hoặc s3proxy, mọi workspace dùng chung một khóa; dữ liệu tách theo tiền tố đường dẫn. Khóa riêng cho từng workspace chỉ có khi dùng MinIO. - **Azure Blob đi qua s3proxy và chưa được kiểm trên tài khoản thật.** Nếu cần chắc chắn, dùng MinIO tự vận hành trên Azure Disk. - **Terraform là mẫu tham khảo**, mới qua `terraform fmt` và `terraform validate`, chưa chạy trên tài khoản đám mây thật. Xem [Terraform tham khảo](/vi/docs/self-host/terraform). - **Chỉ một bản cài trong mỗi namespace**, vì Service của `api` có tên cố định là `api`. ## Các bước 1. Chuẩn bị hạ tầng theo [Yêu cầu và cỡ máy](/vi/docs/self-host/requirements), hoặc dựng bằng [Terraform tham khảo](/vi/docs/self-host/terraform). 2. Liên hệ DataxLand để nhận tệp giấy phép và quyền kéo ảnh. 3. [Cài bằng Helm](/vi/docs/self-host/helm). 4. Nếu mạng không ra Internet: [Chế độ cách ly mạng](/vi/docs/self-host/airgapped). 5. Lên lịch sao lưu và diễn tập khôi phục: [Nâng cấp và sao lưu](/vi/docs/self-host/upgrade-backup). ## Liên quan - [Kiến trúc](/vi/docs/architecture) - [Bảo mật và quyền riêng tư](/vi/docs/security-privacy) - [Gói Doanh nghiệp](/vi/enterprise) --- # Giấy phép offline > Tệp giấy phép của bản tự host - nội dung, cách gắn bằng Secret, các trạng thái và ý nghĩa, ân hạn, chế độ chỉ đọc không khóa dữ liệu, gia hạn, lệnh license-status và chỉ số dx_license_days_left. Bản tự host dùng **giấy phép offline**: một tệp `license.json` DataxLand cấp theo hợp đồng. Bản cài kiểm chữ ký của tệp bằng khóa công khai có sẵn trong ảnh, **không gọi về DataxLand** và chạy được trong mạng kín. ## Nội dung tệp Tệp JSON gồm định dạng (`dataxland-license/1`), mã khóa ký, phần nội dung và chữ ký số. Phần nội dung ghi: | Trường | Ý nghĩa | | --- | --- | | `license_id` | Mã giấy phép | | `customer` | Tên khách hàng | | `edition`, `plan` | Phiên bản và gói (Doanh nghiệp) | | `limits.workspaces` | Số workspace tối đa; `null` là không giới hạn | | `limits.seats` | Số người dùng tối đa; `null` là không giới hạn | | `features` | Danh sách tính năng theo hợp đồng, hiện ở trang quản trị | | `issued_at`, `not_before`, `expires_at` | Ngày cấp, ngày bắt đầu hiệu lực, ngày hết hạn | | `grace_days` | Số ngày ân hạn sau khi hết hạn, mặc định 30 | | `deployment` | `selfhost` | Sửa phần nội dung làm chữ ký sai và giấy phép thành không hợp lệ. Cần đổi giới hạn hay thời hạn, liên hệ DataxLand để nhận tệp mới. ## Gắn giấy phép ```bash kubectl -n dataxland create secret generic dataxland-license --from-file=license.json=./license.json ``` ```yaml license: existingSecret: dataxland-license key: license.json # tên khóa trong Secret chứa tệp ``` Chart gắn tệp chỉ đọc vào `/etc/dataxland/license/license.json` của `api`, `worker` và `mcp`. Cài khi chưa có giấy phép thì Helm in cảnh báo kèm lệnh tạo Secret và nâng cấp. ## Trạng thái Bản cài kiểm giấy phép lúc khởi động, rồi lại **mỗi giờ** và **mỗi khi tệp đổi**. | Trạng thái | Khi nào | Bản cài | | --- | --- | --- | | `valid` | Trong thời hạn | Hoạt động đủ, áp giới hạn workspace và người dùng | | `grace` | Đã hết hạn, còn trong ân hạn | Như `valid`; trang quản trị hiện cảnh báo | | `expired` | Hết cả ân hạn | Chỉ đọc | | `not_yet_valid` | Chưa tới `not_before` | Chỉ đọc | | `invalid` | Sai định dạng, sai chữ ký, khóa ký lạ, không dành cho bản tự host | Chỉ đọc | | `missing` | Chưa gắn tệp | Chỉ đọc | ### Chế độ chỉ đọc Chế độ chỉ đọc **không khóa dữ liệu của bạn**: - Vẫn chạy: dashboard, hỏi Si, MCP, xuất dữ liệu, đăng nhập. - Bị chặn: tạo workspace, mời người dùng, chạy build hoặc làm mới dữ liệu. API trả lỗi 402 mã `license_inactive`. Dữ liệu dừng ở lần build cuối cùng cho tới khi có giấy phép hợp lệ. ### Giới hạn - **Workspace**: đếm các workspace đang hoạt động trên toàn bản cài, gồm cả workspace mẫu. - **Người dùng**: đếm các tài khoản chưa bị khóa trên toàn bản cài. Đạt giới hạn thì không tạo thêm workspace hoặc không mời thêm người (lỗi 402 mã `license_limit`); những gì đang có vẫn dùng bình thường. Khóa tài khoản không còn dùng sẽ giải phóng chỗ. ## Xem trạng thái Trong ứng dụng: **Quản trị → Vận hành**, mục **Triển khai và giấy phép** hiện khách hàng, mã giấy phép, ngày hết hạn, số ngày còn lại (gồm ân hạn), mức dùng so với giới hạn và danh sách tính năng. Từ dòng lệnh: ```bash kubectl -n dataxland exec deploy/dataxland-worker -- python -m pipelines.cli license-status ``` Lệnh in JSON gồm trạng thái giấy phép, mức dùng, chế độ cách ly, và trả mã thoát 1 khi giấy phép không còn hiệu lực, nên dùng được trong script kiểm tra. ## Theo dõi hạn `api` xuất chỉ số Prometheus `dx_license_days_left`: số ngày còn lại tới khi chuyển sang chỉ đọc (gồm ân hạn), nhãn `state` là trạng thái hiện tại. Ví dụ luật cảnh báo: ```yaml - alert: DataxLandLicenseExpiring expr: dx_license_days_left < 45 for: 1h annotations: summary: Giấy phép DataxLand còn dưới 45 ngày; liên hệ DataxLand để gia hạn ``` ## Gia hạn 1. Liên hệ DataxLand để nhận tệp giấy phép mới. 2. Thay nội dung Secret: ```bash kubectl -n dataxland create secret generic dataxland-license \ --from-file=license.json=./license.json --dry-run=client -o yaml | kubectl apply -f - ``` 3. Kubernetes cập nhật tệp đã gắn vào pod sau ít phút; bản cài thấy tệp đổi và đọc lại, **không cần khởi động lại**. Kiểm bằng `license-status` hoặc trang quản trị. ## Liên quan - [Cài bằng Helm](/vi/docs/self-host/helm) - [Chế độ cách ly mạng](/vi/docs/self-host/airgapped) - [Gói Doanh nghiệp](/vi/enterprise) --- # Yêu cầu và cỡ máy > Hạ tầng cần có trước khi tự host DataxLand (Kubernetes, Postgres 16, object storage tương thích S3, ổ dùng chung, ingress và TLS), tài nguyên mặc định của từng thành phần và cách chọn object storage theo đám mây. ## Hạ tầng cần có | Hạng mục | Yêu cầu | | --- | --- | | Kubernetes | 1.27 trở lên, nút amd64 hoặc arm64 (ảnh có cả hai kiến trúc) | | Postgres | Bản 16, dịch vụ có quản lý (RDS, Cloud SQL, Azure Database for PostgreSQL) hoặc cụm Postgres của bạn, có sao lưu | | Database | Hai database cùng một user: `dx` (metadata) và `dx_lake` (catalog của kho). Ứng dụng tự tạo `dx_lake` nếu user có quyền `CREATEDB` | | Object storage | Tương thích S3: hai bucket, một cho kho (mặc định `dx-lake`), một cho sao lưu (mặc định `dx-backups`) | | Ổ dùng chung | StorageClass cấp được PVC `ReadWriteMany` (EFS, Filestore, Azure Files, NFS, CephFS). Một nút: `ReadWriteOnce` đủ | | Ingress | Ingress controller có sẵn trong cụm và tên miền cho `web`, ví dụ `dataxland.corp.example` | | TLS | Chứng chỉ trong Secret, hoặc cert-manager cấp tự động | | Email | Máy chủ SMTP để gửi thư mời, đặt lại mật khẩu, báo cáo | | Model AI | Khóa API của nhà cung cấp model, hoặc model nội bộ tương thích OpenAI (vLLM, Ollama, LM Studio, TGI) | Tùy chọn: External Secrets Operator (đọc bí mật từ kho bí mật của bạn), Prometheus Operator (thu chỉ số), CNI hỗ trợ NetworkPolicy (Calico, Cilium, Azure NPM, GKE Dataplane V2, AWS VPC CNI có bật policy). Pod chạy với user không phải root (uid 10001), hệ thống tệp gốc chỉ đọc, bỏ mọi capability, `seccompProfile: RuntimeDefault`. Các thiết lập này khớp yêu cầu của chuẩn Pod Security "restricted"; chúng tôi chưa thử trên cụm bắt buộc chuẩn đó. ## Tài nguyên mặc định Theo `values.yaml` của chart. "Yêu cầu" là phần Kubernetes giữ chỗ; "giới hạn" là trần bộ nhớ của mỗi pod. | Thành phần | Số bản | CPU yêu cầu | Bộ nhớ yêu cầu | Bộ nhớ giới hạn | | --- | --- | --- | --- | --- | | `api` | 2 | 0,5 | 1 Gi | 3 Gi | | `web` | 2 | 0,1 | 256 Mi | 768 Mi | | `mcp` | 1 | 0,25 | 512 Mi | 2 Gi | | `worker` | 1 | 1 | 2 Gi | 7 Gi | | **Tổng** | | **2,45** | **5 Gi** | **16,5 Gi** | Chỉnh bằng `api.resources`, `web.resources`, `mcp.resources`, `worker.resources`. Bộ nhớ của `api` và `mcp` chủ yếu dành cho kho đọc: `api.readers` (mặc định `max: 8`, `memory: 256MB`) và `mcp.readers` (`max: 4`, `memory: 256MB`); tích hai số là trần bộ nhớ kho đọc của mỗi pod. `worker.threads` (mặc định 4) là số luồng khi build. ## Gợi ý cỡ Các con số dưới đây là **ước lượng** để bắt đầu, chưa đo trên tải thật của bạn. Theo dõi bộ nhớ và thời gian build trong vài tuần đầu rồi chỉnh. | | Nhỏ | Vừa | Lớn | | --- | --- | --- | --- | | Số workspace | đến 10 | 10 đến 50 | trên 50 | | Nút Kubernetes | 3 × 4 vCPU, 16 GB | 3 × 8 vCPU, 32 GB | 4 nút trở lên × 8 vCPU, 32 GB | | `worker` giới hạn bộ nhớ | 7 Gi (mặc định) | 12 Gi | 16 Gi trở lên | | `api` | 2 bản (mặc định) | bật `api.autoscaling` | bật `api.autoscaling`, tăng `maxReplicas` | | Postgres | 2 vCPU, 4 GB | 4 vCPU, 16 GB | 8 vCPU, 32 GB | | Ổ dùng chung | 100 Gi (mặc định) | 250 Gi | 500 Gi trở lên | Dung lượng object storage phụ thuộc lượng dữ liệu nguồn; Parquet nén thường nhỏ hơn nhiều so với dữ liệu gốc. Bucket sao lưu cần chỗ cho số bản giữ lại (mặc định 7 ngày, 4 tuần, 6 tháng). `worker` chỉ chạy một bản, nên khi dữ liệu lớn lên thì tăng bộ nhớ và `worker.threads` của nó, không tăng số bản. ## Object storage theo đám mây DataxLand nói giao thức S3. Cách nối từng loại, đặt trong `objectStorage` của values: | Nơi lưu | `objectStorage.endpoint` | `urlStyle` | Khóa | Ghi chú | | --- | --- | --- | --- | --- | | AWS S3 | `s3..amazonaws.com` | `vhost` | Access key tĩnh của IAM user | IRSA, Pod Identity chưa dùng được | | Google Cloud Storage | `storage.googleapis.com` | `path` | Khóa HMAC của service account | Qua API tương thích S3; đường dẫn vẫn là `s3://`, không dùng `gs://` | | Azure Blob Storage | để trống, bật `s3proxy.enabled` | `path` | Cặp khóa S3 do bạn đặt cho s3proxy | s3proxy chạy trong cụm trước Storage Account. **Chưa kiểm trên tài khoản thật** | | On-prem | MinIO, Ceph RGW, hoặc object storage tương thích S3 của nhà cung cấp trong nước | thường `path` | Theo hệ thống | MinIO cho phép khóa riêng từng workspace | - Trên S3, GCS và s3proxy, đặt `objectStorage.tenantKeys: "off"`: một khóa cho cả bucket, dữ liệu mỗi workspace nằm dưới tiền tố riêng. - Với MinIO, `objectStorage.tenantKeys: minio` cấp cho mỗi workspace một khóa chỉ đọc ghi được vùng của nó. Khi đó khóa quản trị MinIO chỉ nằm ở `worker`; chart tự bỏ khóa này khỏi `api` và `mcp`. - Phương án thay cho Azure nếu không muốn qua s3proxy: MinIO tự vận hành trên Azure Disk. - Nên bật versioning cho cả hai bucket, và khóa ghi một lần (Object Lock, retention, immutability) cho bucket sao lưu. ## Mạng Các pod cần nối được tới: Postgres, object storage, máy chủ model AI, SMTP, các database nguồn bạn định kết nối, và DNS của cụm. Nếu dùng chế độ cách ly mạng, đó cũng là danh sách duy nhất được phép; xem [Chế độ cách ly mạng](/vi/docs/self-host/airgapped). ## Liên quan - [Cài bằng Helm](/vi/docs/self-host/helm) - [Terraform tham khảo](/vi/docs/self-host/terraform) --- # Terraform tham khảo (AWS, GCP, Azure) > Module Terraform mẫu dựng mạng, cụm Kubernetes có quản lý, Postgres, object storage, ổ dùng chung và kho bí mật rồi cài Helm chart DataxLand trên AWS, GCP hoặc Azure; là mẫu tham khảo, chưa chạy trên tài khoản thật. Các module này là **mẫu tham khảo**. Chúng mới qua `terraform fmt -check` và `terraform validate`, **chưa chạy `plan` hay `apply` trên tài khoản đám mây thật**. Tên SKU, hạn mức theo vùng, quyền IAM tối thiểu và thời gian chờ có thể phải chỉnh. Đội hạ tầng của bạn hoặc đối tác triển khai chép thư mục của đám mây mình dùng vào repo hạ tầng riêng rồi điều chỉnh. DataxLand cung cấp ba thư mục `aws/`, `gcp/`, `azure/`. Mỗi thư mục đọc được độc lập, không dùng module chung. Bước cuối của mỗi thư mục cài [Helm chart](/vi/docs/self-host/helm) bằng `helm_release`. ## Mỗi module dựng gì | | AWS | GCP | Azure | | --- | --- | --- | --- | | Mạng | VPC, subnet công khai và riêng mỗi AZ, NAT, S3 gateway endpoint | VPC, subnet có dải phụ cho pod và service, Cloud NAT, Private Service Access | VNet, subnet cho AKS, Postgres và private endpoint, private DNS | | Kubernetes | EKS, 3 nút `m6i.xlarge` (4 vCPU, 16 GB) | GKE theo vùng, nút riêng, Dataplane V2, 3 nút `e2-standard-4` | AKS, Azure CNI Overlay và Cilium, 3 nút `Standard_D4s_v5` | | Postgres 16 | RDS Multi-AZ, chỉ trong VPC, bắt buộc TLS | Cloud SQL REGIONAL, chỉ IP riêng, chỉ kết nối mã hóa | Flexible Server ZoneRedundant, tích hợp VNet | | Database `dx_lake` | Job `psql` trong cụm | Tạo bằng Terraform | Tạo bằng Terraform | | Ổ dùng chung | EFS, lớp `efs-rwx` | Filestore, lớp `filestore-rwx` (tối thiểu 1 TiB) | Azure Files, lớp có sẵn `azurefile-csi` | | Object storage | S3, `vhost` | GCS qua API tương thích S3, `path` | Blob qua s3proxy trong cụm, `path` | | Khóa object storage | IAM user và access key, chỉ hai bucket | Service account và khóa HMAC, chỉ hai bucket | Cặp khóa S3 ngẫu nhiên cho s3proxy | | Khóa ghi một lần cho sao lưu (tùy chọn) | S3 Object Lock | Retention policy | Immutability policy | | Kho bí mật | Secrets Manager | Secret Manager | Key Vault | | Ingress | Không cài | Không cài | Add-on App Routing (tắt được) | Mỗi module sinh các bí mật của ứng dụng, lưu vào kho bí mật của đám mây và chép vào Secret Kubernetes mà chart đọc. Khóa object storage là khóa tĩnh, một khóa cho cả bucket: ứng dụng chưa dùng được IRSA, Workload Identity hay Managed Identity. ## Chạy Cách chung, chi tiết trong `README.md` của từng thư mục: ```bash cd aws # hoặc gcp, azure cp terraform.tfvars.example terraform.tfvars # sửa theo tài khoản của bạn terraform init terraform apply -target= # lần đầu: dựng cụm trước kubectl create namespace dataxland kubectl -n dataxland create secret generic dataxland-license --from-file=license.json terraform import kubernetes_namespace_v1.this dataxland terraform apply ``` Phải dựng cụm trước vì provider `kubernetes` và `helm` cần cụm đã có. Secret giấy phép do người vận hành tạo ngoài Terraform, trước lần `apply` cuối. ### AWS Cần AWS CLI và quyền tạo các tài nguyên trên. ```bash terraform apply -target=aws_eks_node_group.default -target=aws_eks_addon.efs_csi ``` - Không cài ingress controller: dùng AWS Load Balancer Controller hoặc controller sẵn có. - Số nút cố định; muốn tự co giãn thì cài Cluster Autoscaler hoặc Karpenter. - Bật bảo vệ xóa cho RDS và cụm; RDS tạo snapshot cuối khi xóa. ### GCP Cần `gcloud auth application-default login`. ```bash terraform apply -target=google_container_node_pool.default gcloud container clusters get-credentials -gke --region ``` - Filestore tier `standard` tối thiểu **1 TiB** mỗi PVC. Cần nhỏ hơn: NFS tự vận hành, hoặc đổi tier. - Quyền thư mục gốc của Filestore với uid 10001 chưa được kiểm. ### Azure Cần `az login` và quyền Owner (hoặc Contributor và User Access Administrator) trên subscription. ```bash terraform apply -target=azurerm_kubernetes_cluster.this az aks get-credentials --resource-group -rg --name -aks ``` - Object storage đi qua **s3proxy**, chưa được kiểm với kho DataxLand trên tài khoản thật. - `azurefile-csi` là Azure Files SMB; hiệu năng build trên SMB chưa được đo. Cần POSIX tốt hơn thì tạo lớp Azure Files NFS. - Lần `apply` đầu có thể lỗi 403 khi ghi Key Vault vì quyền chưa có hiệu lực: chờ vài phút rồi chạy lại. ## Sau khi chạy - **State Terraform chứa mọi bí mật**: dùng backend từ xa có mã hóa và giới hạn quyền. - Chép `DX_BACKUP_ENCRYPTION_KEY` (output `backup_encryption_key`) ra nơi lưu ngoại tuyến. Mất khóa là mất mọi bản sao lưu. - Production nên chuyển sang External Secrets Operator đọc thẳng kho bí mật thay cho Secret do Terraform chép; xem [Cài bằng Helm](/vi/docs/self-host/helm#bí-mật-từ-external-secrets-operator). Values thêm cho chart đặt qua biến `helm_extra_values`. - Module không cài ingress controller, cert-manager, External Secrets Operator hay hệ thống giám sát. ## Liên quan - [Yêu cầu và cỡ máy](/vi/docs/self-host/requirements) - [Cài bằng Helm](/vi/docs/self-host/helm) --- # Nâng cấp, sao lưu và khôi phục > Nâng cấp bản tự host bằng helm upgrade (Job migrate chạy trước), lùi bản, sao lưu hằng ngày bằng worker hoặc CronJob, diễn tập khôi phục và khôi phục thật bằng lệnh backup-restore. Các lệnh dưới đây giả định tên bản cài `dataxland` trong namespace `dataxland`. Lệnh vận hành chạy trong pod `worker`: ```bash kubectl -n dataxland exec deploy/dataxland-worker -- python -m pipelines.cli ``` ## Nâng cấp 1. **Đọc ghi chú phát hành** của bản mới: có đổi schema không, có lùi bản được không, có bước nào phải làm tay không. 2. **Sao lưu ngay** và kiểm bản vừa tạo có trạng thái `ok`: ```bash kubectl -n dataxland exec deploy/dataxland-worker -- python -m pipelines.cli backup kubectl -n dataxland exec deploy/dataxland-worker -- python -m pipelines.cli backup-list ``` 3. Mạng kín: [chép ảnh của bản mới](/vi/docs/self-host/airgapped#7-chép-ảnh-vào-registry-nội-bộ) vào registry nội bộ trước. 4. **Nâng cấp**: ```bash helm upgrade dataxland <đường dẫn chart mới> -n dataxland -f values-prod.yaml ``` Helm chạy Job `migrate` trước (`python -m pipelines.cli db-migrate`): tạo bảng, cột, chỉ mục còn thiếu trong Postgres. Job chạy lại được nhiều lần; giới hạn thời gian đặt ở `migrations.activeDeadlineSeconds` (mặc định 600 giây). Job xong thì `api`, `web`, `mcp` được thay dần, còn `worker` dừng rồi chạy bản mới: việc nền (build, lịch làm mới, sao lưu) ngừng vài phút, dashboard và hỏi Si vẫn chạy. 5. **Kiểm tra**: `kubectl -n dataxland get pods`, gọi `/readyz` của `api` như lúc [cài](/vi/docs/self-host/helm#6-kiểm-tra-và-đăng-nhập), mở một dashboard, xem **Quản trị → Vận hành**. Job `migrate` lỗi thì Helm dừng và các thành phần đang chạy giữ bản cũ. Xem log bằng `kubectl -n dataxland logs job/dataxland-migrate`. ### Lùi bản `helm rollback dataxland ` chỉ an toàn khi bản mới **chưa đổi schema theo cách bản cũ không đọc được**; ghi chú phát hành nói rõ điều này. Nếu không chắc, cách mặc định là cài lại bản cũ rồi khôi phục bản sao lưu đã tạo ở bước 2. ## Sao lưu Một bản sao lưu gồm Postgres metadata, tệp của từng workspace (tệp tải lên, cấu hình, bản duyệt, bí mật đã mã hóa) và kho dữ liệu của mọi workspace. Mọi tệp được **mã hóa bằng `DX_BACKUP_ENCRYPTION_KEY`** trước khi ghi vào bucket sao lưu. Dữ liệu kho chỉ được tải lên một lần rồi các bản sau tham chiếu lại, nên các lượt sau nhỏ hơn lượt đầu. ### Lịch Mặc định `worker` tự sao lưu mỗi ngày: ```yaml deployment: timezone: Asia/Ho_Chi_Minh objectStorage: backup: enabled: true bucket: dx-backups prefix: "" endpoint: "" # trống = cùng endpoint với kho at: "02:00" # giờ theo deployment.timezone keep: "7,4,6" # giữ 7 bản ngày, 4 bản tuần, 6 bản tháng ``` Muốn Kubernetes quản lịch, bật CronJob. Khi đó chart tự tắt lịch của `worker`: ```yaml backupCronJob: enabled: true schedule: "0 19 * * *" # 02:00 giờ Việt Nam nếu cụm dùng UTC restoreDrill: enabled: true schedule: "0 21 * * 0" # diễn tập hằng tuần ``` Khuyến nghị: - Đặt bucket sao lưu ở vùng hoặc hệ thống khác với bucket kho. Có thể dùng khóa riêng (`DX_BACKUP_S3_KEY_ID`, `DX_BACKUP_S3_SECRET`) và endpoint riêng (`objectStorage.backup.endpoint`). - Bật versioning và khóa ghi một lần (Object Lock, retention, immutability) cho bucket sao lưu. - Không xóa tay thư mục `_objects/` trong bucket sao lưu: mọi bản sao lưu cần nó để khôi phục kho. - Vẫn giữ sao lưu của dịch vụ Postgres có quản lý; hai lớp bổ sung cho nhau. ### Giữ hai khóa ở hai nơi Hai khóa sau **không nằm trong bản sao lưu** và không có cách lấy lại: - `DX_SECRET_KEY`: giải mã mật khẩu nguồn, token đã lưu. Mất thì phải nối lại mọi nguồn dữ liệu. - `DX_BACKUP_ENCRYPTION_KEY`: giải mã bản sao lưu. Mất thì **mọi bản sao lưu đã mã hóa bằng nó không dùng được**. Giữ mỗi khóa ở hai nơi: kho bí mật của công ty và một bản ngoại tuyến (bản in hoặc USB mã hóa cất két). Giữ hai khóa tách nhau, do người khác nhau quản lý nếu được. ## Diễn tập khôi phục ```bash kubectl -n dataxland exec deploy/dataxland-worker -- python -m pipelines.cli restore-drill kubectl -n dataxland exec deploy/dataxland-worker -- python -m pipelines.cli restore-drill --backup ``` Lệnh khôi phục bản mới nhất (hoặc bản chỉ định) vào một database tạm và một vùng lưu tạm, so số dòng và tổng các cột số với lúc sao lưu, kiểm tổng băm các tệp, rồi xóa phần tạm. **Không đụng dữ liệu đang chạy.** User Postgres cần quyền tạo database. Chạy ít nhất hằng tuần (hoặc bật `backupCronJob.restoreDrill`). Lần diễn tập thành công cũng chứng minh `DX_BACKUP_ENCRYPTION_KEY` đang giữ là đúng. Chỉ số `dx_backup_last_success_timestamp_seconds` (nhãn `kind`) cho biết lần sao lưu và diễn tập thành công gần nhất. ## Khôi phục thật `backup-restore` ghi đè dữ liệu. Chọn bản trước: ```bash kubectl -n dataxland exec deploy/dataxland-worker -- python -m pipelines.cli backup-list ``` Tham số của `backup-restore`: | Tham số | Việc | | --- | --- | | `--backup ` | Bản sao lưu, bắt buộc | | `--meta` | Nạp Postgres metadata; mọi bảng của database đích phải chưa có dữ liệu | | `--tenant ` | Khôi phục tệp và kho của workspace này; lặp lại được | | `--all-tenants` | Mọi workspace có trong bản sao lưu | | `--force` | Ghi đè tệp và thay kho đang có | ### Một workspace hỏng Metadata còn nguyên, chỉ kho hoặc tệp của một workspace hỏng: ```bash kubectl -n dataxland exec deploy/dataxland-worker -- \ python -m pipelines.cli backup-restore --backup --tenant --force ``` Sau đó chạy một lần làm mới cho workspace đó để nạp dữ liệu nguồn mới hơn thời điểm sao lưu. ### Khôi phục toàn phần Khi mất Postgres metadata, mất bucket kho hoặc dựng lại trên cụm mới: 1. Tạo Postgres mới với database `dx` và `dx_lake` trống. 2. Cài chart **cùng phiên bản** với bản cài lúc sao lưu, dùng **cùng** `DX_SECRET_KEY`, `DX_BACKUP_ENCRYPTION_KEY` và cùng nơi lưu sao lưu. Chưa cho ai đăng nhập: `kubectl -n dataxland scale deploy/dataxland-web --replicas=0` (tắt `web.autoscaling` nếu đang bật). 3. Nạp metadata: ```bash kubectl -n dataxland exec deploy/dataxland-worker -- \ python -m pipelines.cli backup-restore --backup --meta ``` 4. Nạp tệp và kho của mọi workspace: ```bash kubectl -n dataxland exec deploy/dataxland-worker -- \ python -m pipelines.cli backup-restore --backup --all-tenants ``` Dữ liệu kho được lấy từ bucket sao lưu, nên bucket kho mới có thể trống. 5. Khởi động lại các thành phần (`kubectl -n dataxland rollout restart deploy`), gọi `/readyz`, mở dashboard của một workspace và so với số trước sự cố. Có thể chạy thêm `restore-drill --backup `. 6. Mở lại `web` (`kubectl -n dataxland scale deploy/dataxland-web --replicas=2`). Lần làm mới theo lịch kế tiếp nạp lại dữ liệu nguồn sau thời điểm sao lưu; tệp Excel tải lên sau thời điểm đó phải tải lại. Nếu `--meta` báo database đích đã có dữ liệu, hoặc bạn không chắc nên chọn bản nào, liên hệ DataxLand trước khi chạy tiếp. ## Liên quan - [Cài bằng Helm](/vi/docs/self-host/helm) - [Giấy phép](/vi/docs/self-host/license) - [Bảo mật và quyền riêng tư](/vi/docs/security-privacy) --- # Xác thực hai lớp (2FA) và tài khoản > Bật 2FA bằng ứng dụng tạo mã (TOTP), lưu 10 mã khôi phục, tắt 2FA, đổi mật khẩu và đăng xuất các thiết bị khác. ## Bật 2FA DataxLand dùng mã 6 số từ ứng dụng tạo mã (TOTP) như Google Authenticator, Microsoft Authenticator, 1Password. 1. Mở **Tài khoản** từ menu người dùng. Thẻ **Xác thực hai lớp (2FA)** ghi **Chưa bật**. 2. Bấm **Cài 2FA**. 3. Quét mã QR bằng ứng dụng (hoặc nhập khóa thủ công). 4. Nhập mã 6 số đang hiện, bấm **Bật 2FA**. 5. DataxLand hiện **10 mã khôi phục** một lần. Lưu ở nơi an toàn (trình quản lý mật khẩu), bấm **Tôi đã lưu mã**. Từ lần đăng nhập sau, bạn nhập mã 6 số sau mật khẩu. Mất điện thoại thì dùng một mã khôi phục; mỗi mã dùng một lần. ## Tắt 2FA Bấm **Tắt 2FA** và nhập mật khẩu (tài khoản chỉ đăng nhập bằng Google thì nhập mã 2FA). Nếu workspace bắt buộc 2FA cho vai trò của bạn, tắt đi thì bạn chỉ vào được trang tài khoản tới khi bật lại. ## Các thẻ khác trên trang Tài khoản | Thẻ | Dùng để | | --- | --- | | Hồ sơ | Tên hiển thị | | Đổi mật khẩu | Mật khẩu mới tối thiểu 8 ký tự | | Thiết bị đang đăng nhập | **Đăng xuất** một thiết bị, hoặc **Đăng xuất mọi thiết bị** | | Kết nối chat | Nối Telegram, Slack, Microsoft Teams để hỏi Si | | Dữ liệu của bạn | Tải dữ liệu cá nhân, xóa tài khoản | ## Phiên đăng nhập Phiên giữ tối đa 30 ngày, tự hết sau 7 ngày không dùng. Sai mật khẩu 5 lần thì tài khoản tạm khóa đăng nhập 15 phút. ## Liên quan - [Thành viên và vai trò](/vi/docs/workspace/members) - [Bảo mật và quyền riêng tư](/vi/docs/security-privacy) - [Xuất và xóa dữ liệu](/vi/docs/workspace/export-delete) --- # Nhật ký kiểm toán > Xem ai đã làm gì trong workspace — đăng nhập, thành viên và vai trò, quyền dữ liệu, SSO, token MCP, xuất dữ liệu — lọc theo người, hành động, thời gian và xuất CSV. Quản trị trở lên mở **Cài đặt → Nhật ký kiểm toán**. Lọc và xuất CSV có ở **mọi gói trả phí**; gói Miễn phí vẫn xem được các sự kiện mới nhất ở **Thành viên & vai trò**. ## Ghi những gì - Thành viên: mời, nhận, thu hồi lời mời; đổi vai trò (kể cả vai trò tùy chỉnh); xóa, rời; chuyển quyền sở hữu; bắt buộc 2FA. - Vai trò tùy chỉnh: tạo, sửa (quyền thêm/bớt), xóa. - Quyền dữ liệu: tạo, sửa, xóa luật; đổi cài đặt. - SSO: tạo, sửa, xóa kết nối; thêm, xác minh, gỡ domain; bật/tắt bắt buộc SSO; đăng nhập SSO; tự cấp tài khoản; đăng nhập tài khoản phá kính; từ chối đăng nhập. - Token MCP, token dashboard nhúng: tạo, thu hồi. Xuất workspace, xuất nhật ký kiểm toán. Không có mật khẩu, token hay mã bí mật trong nhật ký. ## Lọc và xuất Lọc theo **người làm**, **hành động** (một hành động hoặc cả nhóm, ví dụ "Quyền dữ liệu (mọi hành động)"), **từ ngày – đến ngày**. **Xuất CSV** tải đúng bộ lọc hiện tại (tối đa 100.000 dòng, UTF-8 mở được bằng Excel); lần xuất cũng được ghi vào nhật ký. ## Lưu giữ Sự kiện giữ **2 năm**; địa chỉ IP và trình duyệt giữ **180 ngày** rồi tự xóa. Xóa workspace không xóa nhật ký (là bằng chứng). --- # Quyền dữ liệu theo dòng > Giới hạn người hoặc vai trò chỉ thấy một phần dữ liệu — một chi nhánh, một kênh bán — ở mọi nơi có số trong DataxLand, kể cả Si, MCP, chat, báo cáo và cảnh báo. Có từ gói **Doanh nghiệp nhỏ**. Quản trị (hoặc vai trò có quyền "Quyền dữ liệu") cấu hình ở **Cài đặt → Quyền dữ liệu**. ## Luật Một luật gồm: **chiều dữ liệu** của mô hình ngữ nghĩa (Kênh, Chi nhánh, Nền tảng…), **các giá trị được thấy**, và **áp cho** thành viên hoặc vai trò (có sẵn hoặc tùy chỉnh). - Nhiều luật **cùng chiều** áp cho một người: cộng các giá trị (HN + HCM). - Luật **khác chiều**: phải thỏa cả hai (chi nhánh HN **và** kênh Shopee). - Người không có luật nào: thấy toàn bộ — hoặc không thấy gì nếu bật **Người chưa có luật nào không thấy dữ liệu**. - Mặc định **Chủ sở hữu và Quản trị bỏ qua** luật; bỏ chọn để giới hạn cả họ. Người sửa luật phải không bị giới hạn (không ai tự nới quyền của mình được). ## Áp dụng ở đâu Điều kiện của luật được thêm vào **mọi câu truy vấn** mà DataxLand chạy để tính số, nên tổng, so sánh kỳ, top N, tỷ lệ và phân tích "vì sao" đều tính trên đúng các dòng được phép — không có con số nào tính trên toàn bộ rồi mới lọc. | Nơi | Tính theo quyền của | |---|---| | Dashboard, trang, inspector, truy vấn, vì sao, xem trước báo cáo | người đang xem | | Si trong ứng dụng; hỏi Si trong chat riêng với bot (Telegram, Slack, Teams) | người hỏi (tài khoản đã nối) | | Nhóm Telegram, kênh Slack, kênh/nhóm chat Teams | chỉ trả lời người **không bị giới hạn** (cả nhóm thấy câu trả lời); người bị giới hạn được nhắc nhắn riêng cho bot, trừ khi bật "Cho phép trả lời trong nhóm theo quyền người hỏi" | | MCP | người tạo token | | Báo cáo định kỳ, cảnh báo | người tạo báo cáo / cảnh báo (người đó rời workspace thì lần gửi bị bỏ qua) | Chỉ số nằm trên bảng **không có** chiều bị giới hạn (ví dụ chi phí quảng cáo không chia theo chi nhánh) mặc định bị **ẩn** với người bị giới hạn; đổi luật sang "Vẫn hiện số toàn workspace" nếu bạn chấp nhận họ thấy số đó. Người đang bị giới hạn không mở được các màn đọc **dữ liệu thô**: nguồn dữ liệu, SQL trên nguồn, hồ sơ dữ liệu, xuất workspace — và Si không dùng [sandbox SQL/Python](/vi/docs/ask/sandbox) cho họ (bản trích lấy cả bảng). ## Hạ gói Luật đã có vẫn được áp dụng (tắt luật khi hết gói sẽ làm lộ dữ liệu), chỉ không tạo, sửa được. Mọi thay đổi luật và cài đặt được ghi vào [nhật ký kiểm toán](/vi/docs/workspace/audit-log). --- # Xuất và xóa dữ liệu > Xuất toàn bộ dữ liệu workspace (Parquet, CSV, định nghĩa), tải dữ liệu cá nhân, xóa workspace với 7 ngày khôi phục và xóa tài khoản. Dữ liệu là của bạn: xuất ra bất kỳ lúc nào, kể cả khi đã hết hạn mức gói. ## Xuất dữ liệu workspace 1. Vào **Cài đặt → Dữ liệu & quyền riêng tư** (chỉ Chủ sở hữu). 2. Ở thẻ **Xuất dữ liệu workspace**, đánh dấu **Gồm cả dữ liệu nguồn (lớp raw)** nếu cần dữ liệu nạp nguyên trạng. 3. Bấm **Tạo bản xuất**. Khi xong, bấm **Tải về**. Liên kết tải có hiệu lực 15 phút; bản xuất được giữ 7 ngày. File `.zip` gồm: | Phần | Định dạng | | --- | --- | | README, manifest | Mô tả nội dung | | Cấu hình workspace, ánh xạ đã duyệt (đã bỏ mật khẩu, khóa) | YAML | | Mô hình ngữ nghĩa, chỉ số của workspace, trang, kiến thức, cảnh báo, lịch | JSON | | Bảng chuẩn hóa và bảng chỉ số | Parquet; kèm CSV cho bảng đến 100.000 dòng | | Nhật ký kiểm toán (không có IP) | JSON | Cột thông tin cá nhân vẫn ở dạng băm. ## Tải dữ liệu cá nhân Ở trang **Tài khoản**, thẻ **Dữ liệu của bạn**, bấm **Tải dữ liệu của tôi**: một file JSON gồm hồ sơ, workspace bạn tham gia và vai trò, phiên đăng nhập, nhật ký bảo mật về bạn và các câu hỏi bạn đã hỏi Si (không gồm câu trả lời, vốn là dữ liệu của workspace). ## Xóa workspace 1. Vào **Cài đặt → Nâng cao** (chỉ Chủ sở hữu), chọn xóa workspace. 2. **Gõ tên workspace để xác nhận** và nhập **Mật khẩu của bạn** (tài khoản chỉ dùng Google: **Mã 2FA**). 3. Xác nhận. Workspace chờ xóa 7 ngày. Trong thời gian đó, Chủ sở hữu khôi phục ở trang **Tài khoản → Workspace đang chờ xóa → Khôi phục**. Token MCP chỉ gắn với workspace đó không được khôi phục. Sau 7 ngày dữ liệu bị xóa; bản sao lưu tự hết hạn sau tối đa 6 tháng. Workspace mẫu bị xóa ngay. ## Xóa tài khoản 1. Chuyển quyền sở hữu hoặc xóa mọi workspace bạn đang sở hữu (không xóa được tài khoản khi còn sở hữu workspace). 2. Ở **Tài khoản → Dữ liệu của bạn**, bấm **Gửi liên kết xóa tài khoản**. 3. Mở email (liên kết có hiệu lực 1 giờ), bấm **Xóa tài khoản**. Token MCP của bạn bị thu hồi; tên của bạn trong nhật ký được thay bằng mã ẩn danh. ## Liên quan - [Bảo mật và quyền riêng tư](/vi/docs/security-privacy) - [Chính sách riêng tư](/vi/privacy) - [Thỏa thuận xử lý dữ liệu](/vi/dpa) --- # Thành viên và vai trò > Mời đồng nghiệp vào workspace, chọn vai trò Quản trị, Phân tích hoặc Xem, thu hồi lời mời, chuyển quyền sở hữu, bắt buộc 2FA và xem nhật ký bảo mật. ## Vai trò | Vai trò | Làm được | | --- | --- | | Chủ sở hữu | Mọi quyền, gói và thanh toán, thành viên, xóa workspace | | Quản trị | Nguồn dữ liệu, duyệt đề xuất, cài đặt, token MCP, kích hoạt chỉ số, duyệt kiến thức | | Phân tích | Hỏi Si, khám phá dữ liệu, tạo chỉ số và trang nháp, báo cáo và cảnh báo | | Xem | Chỉ xem dashboard và trang dùng chung; không hỏi Si | Mỗi workspace có đúng một Chủ sở hữu. ## Mời thành viên Chỉ Chủ sở hữu mời, đổi vai trò hoặc xóa thành viên. 1. Vào **Cài đặt → Thành viên**. 2. Điền **Email người được mời**, chọn **Vai trò** (Quản trị, Phân tích hoặc Xem). 3. Bấm **Gửi lời mời**. Lời mời có hạn 7 ngày. DataxLand gửi email và hiện liên kết để bạn gửi tay (chỉ hiện một lần). Lời mời nằm ở thẻ **Lời mời đang chờ**; bấm **Thu hồi** để hủy. Mời lại cùng email thì lời mời cũ bị thay. Mỗi thành viên và mỗi lời mời đang chờ tính một chỗ trong số người dùng của gói. ## Nhận lời mời Người được mời mở liên kết, thấy trang **Lời mời tham gia workspace**: - đã có tài khoản: **Đăng nhập để nhận lời mời**, rồi **Nhận lời mời**; - chưa có: **Tạo tài khoản bằng email được mời**. Phải đăng nhập bằng **đúng email được mời** và email đó đã xác thực. ## Đổi vai trò, xóa, rời Bảng thành viên có cột **Người dùng**, **Vai trò**, **Lần cuối vào**. Chủ sở hữu đổi vai trò hoặc bấm **Xóa**. Thành viên tự rời bằng **Rời workspace**. ## Chuyển quyền sở hữu Bấm **Chuyển sở hữu** trên một thành viên, nhập mật khẩu của bạn (hoặc mã 2FA nếu tài khoản chỉ dùng Google), bấm **Chuyển quyền**. Bạn trở thành Quản trị. ## Bắt buộc 2FA Ở thẻ **Bảo mật** (chỉ Chủ sở hữu), đánh dấu **Bắt buộc 2FA cho Chủ sở hữu và Quản trị**. Người có hai vai trò này mà chưa bật 2FA chỉ vào được trang tài khoản để bật. Xem [Xác thực hai lớp](/vi/docs/workspace/2fa). ## Nhật ký bảo mật Thẻ **Nhật ký bảo mật** (Quản trị trở lên) ghi 50 sự kiện gần nhất: đăng nhập, mời, đổi vai trò, tạo token… ## Liên quan - [Xác thực hai lớp](/vi/docs/workspace/2fa) - [Workspace](/vi/docs/concepts/workspace) - [Gói và hạn mức](/vi/docs/billing/quotas) --- # Múi giờ, tiền tệ và định dạng > Đặt múi giờ, tiền tệ và định dạng số, ngày cho workspace; điều gì thay đổi khi đổi múi giờ hoặc tiền tệ, và vì sao DataxLand không quy đổi tỷ giá. Thiết lập ở **Cài đặt → Chung**, thẻ **Múi giờ, tiền tệ và định dạng**. Cần vai trò Quản trị trở lên. | Ô | Mặc định | Ảnh hưởng | | --- | --- | --- | | Múi giờ | Asia/Ho_Chi_Minh (UTC+07:00) | Ranh giới ngày, tuần, tháng của mọi chỉ số; giờ chạy lịch làm mới, báo cáo | | Tiền tệ | VND | Nhãn tiền trên dashboard, câu trả lời, báo cáo | | Định dạng số và ngày | Việt Nam | Cách hiện số và ngày: Việt Nam, Mỹ, Anh, Singapore, Úc; cũng là ngôn ngữ Si dùng khi câu hỏi quá ngắn để nhận ra (Việt Nam → tiếng Việt, còn lại → tiếng Anh) | ## Khi đổi - **Múi giờ hoặc tiền tệ**: DataxLand build lại dữ liệu từ đầu và dời lịch, báo cáo sang múi giờ mới. Số theo ngày, tuần, tháng và nhãn tiền sẽ thay đổi. Không lưu được khi đang có tác vụ chạy; chờ xong rồi lưu lại. - **Chỉ định dạng**: chỉ đổi cách hiển thị, không build lại. Bấm **Lưu thiết lập**. ## Không quy đổi tỷ giá DataxLand không quy đổi tiền giữa các loại tiền tệ. Nếu nguồn có nhiều loại tiền (ví dụ shop Lazada ở nhiều nước), số được cộng theo giá trị gốc; hãy tách theo kênh hoặc dùng workspace riêng cho mỗi loại tiền. ## Tuần và thời điểm Tuần luôn bắt đầu thứ Hai. Thời điểm lưu theo UTC; chỉ ngày nghiệp vụ theo múi giờ workspace. ## Liên quan - [Chỉ số và lớp ngữ nghĩa](/vi/docs/metrics) - [Cách đồng bộ và lịch làm mới](/vi/docs/concepts/sync-modes) - [Workspace](/vi/docs/concepts/workspace) --- # Vai trò tùy chỉnh > Tạo vai trò với đúng những quyền cần thiết (ví dụ chỉ quản lý báo cáo, hoặc quản trị nhưng không đụng nguồn dữ liệu) ngoài bốn vai trò có sẵn của workspace. Bốn vai trò có sẵn — **Chủ sở hữu, Quản trị, Phân tích, Xem** — vẫn như cũ ([Thành viên](/vi/docs/workspace/members)). Ở gói **Doanh nghiệp**, Chủ sở hữu tạo thêm vai trò ở **Cài đặt → Thành viên & vai trò → Vai trò tùy chỉnh**. ## Danh mục quyền | Mức | Quyền | |---|---| | Xem | Xem dashboard (dashboard, trang, chỉ số, sức khỏe dữ liệu) — luôn có | | Phân tích | Hỏi Si (cả qua Telegram, Slack, Teams); Khám phá dữ liệu (truy vấn, vì sao, inspector, hồ sơ dữ liệu); Kiến thức; Soạn chỉ số và trang; Xem tự động hóa | | Quản trị | Quản lý nguồn dữ liệu (**thấy dữ liệu thô**); Duyệt mô hình; Cài đặt workspace; Đích thông báo; Quản lý báo cáo, cảnh báo; Token MCP; Nhật ký kiểm toán; Mức dùng và bảo mật; Quyền dữ liệu | Quyền của Chủ sở hữu (thành viên, vai trò, bảo mật và SSO, xuất dữ liệu, xóa workspace, thanh toán) không cấp cho vai trò tùy chỉnh được. Mỗi vai trò tùy chỉnh có một **vai trò có sẵn tương đương** — vai trò thấp nhất chứa mọi quyền đã chọn — dùng cho yêu cầu "bắt buộc 2FA cho Chủ sở hữu và Quản trị" và cách đếm chỗ. Ví dụ "Xem + Quản lý báo cáo" tương đương Quản trị nên cũng phải bật 2FA khi workspace bắt buộc. ## Gán vai trò Chọn vai trò ở cột **Vai trò** của danh sách thành viên, hoặc khi gửi lời mời. Vai trò tùy chỉnh cũng dùng được làm vai trò mặc định khi [tự cấp tài khoản qua SSO](/vi/docs/workspace/sso) và trong [luật quyền dữ liệu](/vi/docs/workspace/data-access). Sửa quyền của vai trò có hiệu lực ngay với mọi người đang mang vai trò đó. Muốn xóa vai trò, đổi vai trò của họ trước. Hạ gói xuống dưới Doanh nghiệp: vai trò đã gán vẫn giữ nguyên (không bị nới quyền) nhưng không tạo, sửa được nữa. Tạo, sửa, xóa vai trò và đổi vai trò thành viên được ghi vào [nhật ký kiểm toán](/vi/docs/workspace/audit-log). --- # Đăng nhập một lần (SSO) > Cho nhân viên đăng nhập DataxLand bằng tài khoản công ty qua Microsoft Entra ID, Google Workspace, Okta hoặc IdP OIDC / SAML 2.0; xác minh domain bằng DNS, tự cấp tài khoản và bắt buộc SSO. SSO có ở gói **Doanh nghiệp**. Chủ sở hữu workspace cấu hình ở **Cài đặt → Bảo mật**. ## Cách hoạt động - Kết nối SSO thuộc workspace chính của công ty, còn danh tính đi theo **domain email**: ai có email `@congty.vn` (domain đã xác minh) đăng nhập qua IdP của công ty, dù họ thuộc workspace nào. - Hỗ trợ **OpenID Connect** (khuyến nghị: Entra ID, Google Workspace, Okta, Keycloak, Auth0…) và **SAML 2.0** (SP-initiated). DataxLand kiểm chữ ký `id_token` bằng khóa công khai của IdP, chữ ký SAML bằng chứng chỉ bạn dán vào (không tin chứng chỉ đi kèm thông điệp), cùng issuer, audience, hạn dùng và mã chống phát lại. - **Tự cấp tài khoản (JIT)**: người thuộc domain đăng nhập lần đầu được tạo tài khoản và vào workspace với **vai trò mặc định** (có thể là vai trò tùy chỉnh). Tắt JIT thì chỉ người đã có tài khoản hoặc đã được mời mới vào được. ## 1. Tạo ứng dụng ở IdP | IdP | Giao thức | Redirect / ACS | Issuer nhập vào DataxLand | |---|---|---|---| | Microsoft Entra ID | OIDC (App registrations → Web) | Redirect URI hiện ở trang Bảo mật | Directory (tenant) ID — DataxLand tự ghép `https://login.microsoftonline.com//v2.0` | | Google Workspace | OIDC (Google Cloud → Credentials → OAuth client ID, Web) | Redirect URI | tự điền; nhập domain Google Workspace để chỉ nhận tài khoản công ty | | Okta | OIDC (Applications → Web) hoặc SAML | Redirect URI hoặc ACS URL + Entity ID | Okta domain (vd. `congty.okta.com`) | | IdP khác | OIDC hoặc SAML 2.0 | như trên | Issuer URL (https) | Với SAML: tắt mã hóa assertion, chọn NameID dạng email (hoặc gửi thuộc tính `email`), tải chứng chỉ ký (X.509) dán vào DataxLand. Metadata của DataxLand (SP) ở địa chỉ **Metadata của DataxLand** trên trang Bảo mật. ## 2. Xác minh domain Thêm domain, rồi tạo ở DNS một bản ghi **TXT** tên `_dataxland.` với giá trị hiện trên trang (dạng `dataxland-verification=…`). Bấm **Kiểm tra DNS**; DNS có thể mất vài phút đến vài giờ. Domain email công cộng (gmail.com, outlook.com…) không dùng được. Một domain chỉ thuộc một workspace. ## 3. Bắt buộc SSO Sau khi đã có domain xác minh và **một lần đăng nhập SSO thành công**, bật **Bắt buộc SSO**: người dùng của domain không đăng nhập bằng mật khẩu hoặc Google được nữa, không tự đăng ký, không đặt lại mật khẩu. **Tài khoản phá kính** (tối đa 3, phải bật xác thực hai lớp) vẫn đăng nhập bằng mật khẩu khi IdP gặp sự cố. **Tin MFA của IdP**: bật khi IdP đã bắt buộc MFA; phiên SSO khi đó thỏa yêu cầu "bắt buộc 2FA" của workspace. ## Khi nhân viên nghỉ việc Khóa tài khoản ở IdP thì họ không đăng nhập mới được. Phiên đang mở sống tối đa tới khi hết hạn (7 ngày không dùng); muốn chặn ngay, xóa họ khỏi workspace ở **Thành viên & vai trò**. Đồng bộ tự động từ IdP (SCIM) sẽ có sau. Mọi thay đổi cấu hình, domain, đăng nhập SSO, cấp tài khoản tự động và đăng nhập phá kính được ghi vào [nhật ký kiểm toán](/vi/docs/workspace/audit-log).