Frequently Asked Questions (FAQ)

This document answers the questions most commonly asked while using OntiCards.

1. Basic Usage

Q1: I cannot find the data I want — what should I do?

Possible causes:

• The data card has not been generated yet

• The question is too vague for the system to understand accurately

• The database schema changed recently and has not been refreshed

Solutions:

1. Check the data card generation progress in Data Source Management

1. Click Refresh Data Source if necessary

• × "check inventory" → √ "list products with inventory below 50 at the Guangzhou warehouse"

• × "sales" → √ "count products that sold more than 100 units in the last 30 days"

1. Rephrase the question more specifically, for example:

Q2: Why does "some conditions ignored" appear?

Explanation: The system understood the question, but no matching field could be found for some of the conditions in the current database. To make sure you still get useful results, the system executes only the conditions it can satisfy.

How to reduce this:

• Use business fields and metrics that actually exist in your company's tables

• If you are unsure, first ask: "Which fields related to products can be queried?"

Q3: Do I need any configuration to query multiple databases?

No complex configuration is needed! Just:

1. Add the data sources separately in the system

1. Express your intent naturally in the question

The system will automatically:

1. Find all the data sources and tables involved

1. Query each of them

1. Choose the appropriate integration method (intersection / union / aggregation) based on your semantics

Example questions:

• "Products with stock in both Guangzhou and Shenzhen"

• "Aggregate the sales of all warehouses over the last 30 days"

Q4: Queries are a bit slow — what can I do?

Common causes:

• A single table holds a very large amount of data

• The query conditions are too broad, with no time or scope limits

• On first access, the system needs extra time to understand the table structure

Suggestions:

• Add a time range such as "last 30 days", "this month", or "this week"

• Add necessary filters (region, category, amount range, etc.)

• Avoid querying too many tables or all historical data at once

Q5: The data source schema changed — what do I need to do?

It is recommended to refresh the data source in the system in the following cases:

• A table was added

• A table was removed

• Fields changed significantly (added, removed, or renamed)

• The business meaning of a table changed noticeably

Steps:

1. Locate the data source in Data Source Management

1. Click Refresh Data Source

1. The system will detect the changed tables and update only the affected parts

2. Feature Usage

Q6: What is a data card?

A data card is an automatically generated "data manual" for a table. It contains:

• Table description: what the table is used for

• Field descriptions: the meaning and purpose of each field

• Common query scenarios: how to use the table

• Business keywords: related business terms

Each data card is generated once; afterwards it is used automatically and updated incrementally as needed.

Q7: What is data discovery? Do I need to do it?

What is data discovery: Data discovery helps the system understand relationships between tables (for example, the order table and the customer table are linked through customer_id), so that multi-table queries produce more accurate SQL.

Why it is recommended:

• Improves multi-table query accuracy by 20-25%

• Reduces incorrect JOIN conditions and Cartesian product problems

• Supports relationship detection across data sources

Two ways to run discovery:

• Full discovery: automatically finds all table relationships in one click; great for getting started quickly

• Targeted discovery: provides fine-grained governance over core tables with higher quality

Q8: What is a business glossary?

The business glossary helps the system understand your company's business terms, such as "high-value customers" or "core products".

Example:

The glossary is optional, but without it the system can only interpret queries based on data cards.

Q9: How do I create a data quality check rule?

OntiCards supports three ways to create rules:

Method 1: Template mode (recommended for beginners) Pick a rule from the preset templates; rules for common scenarios are already built in.

Method 2: AI mode (recommended) Describe the rule in everyday language and the system converts it into a quality check rule automatically.

• "Check that email addresses are formatted correctly"

• "Check that phone numbers have 11 digits"

Method 3: Manual mode (for experts) Configure each rule parameter directly.

Q10: What should I keep in mind when running quality checks?

1. Static data: run checks during off-peak hours to make sure the data is not being updated in real time

1. Execution time: quality checks can consume database resources; schedule large-scale checks at night

1. Frequency: run checks on core data on a regular schedule and resolve issues as soon as they are found

Q11: How long are historical query records kept?

The system lets you configure how many days of history are retained:

Data is cleaned up automatically by scheduled tasks, and manual cleanup can also be triggered.

3. Security and Permissions

Q12: How does the system protect data?

• Access isolation: each user can only access the data sources they added; sources are invisible to other users

• Read-only queries: the system only executes queries and provides no way to modify or delete data

• Sensitive information protection: database passwords are stored encrypted and never appear in the UI, results, or logs

• SQL restrictions: only SELECT statements are allowed, combined with an SQL whitelist

Rest assured: OntiCards only helps you "look up" data — it never "modifies" any business data.

Q13: Can I restrict a user's access to specific data?

The current version supports:

• System-level user isolation: each user can only access the data sources they added

• Database account permissions: once the query hits the database, the permissions of the database account connected to the data source apply

Planned: a fine-grained permission system (field-level and row-level) will be provided in a future release.

Q14: Can multiple users share one data source?

Yes. Each user can add their own data sources, or share the connection details so other users can add the same source.

Note: when the same data source is added by multiple users, its schema information is kept in sync for everyone.

4. Deployment and Operations

Q15: What deployment methods are supported?

The recommended approach is a one-command deployment with Docker Compose.

Environment requirements:

• Docker 20.10+

• Docker Compose 2.0+

• 2-core CPU / 4GB RAM (minimum)

See the deployment guide for detailed steps.

Q16: Which operating systems are supported?

OntiCards can be deployed on any operating system that supports Docker:

• Linux (Ubuntu, CentOS, Debian, etc.)

• macOS

• Windows (via WSL2)

Q17: Which databases are supported?

Q18: How much memory do I need?

Q19: How do I upgrade to a new version?

# Enter the project directory
cd onticards

# Pull the latest code
git pull

# Update Docker images
docker-compose pull

# Restart services
docker-compose up -d

Q20: How do I back up data?

# Backup the database
docker-compose exec backend tar -czf /backup/db.tar.gz /app/data/

# Copy the backup file out
docker-compose cp backend:/backup/db.tar.gz ./backup/

5. Performance and Optimization

Q21: Why is the first query slow?

On first access to a table, the system needs to:

1. Understand the table structure and business meaning

1. Generate a data card

1. Build a vector index

Subsequent queries are much faster because this information is cached.

Q22: Complex queries (e.g. multi-table joins) are inaccurate — what can I do?

1. Run data discovery first so the system understands the table relationships

1. Enrich the data card information to provide more business context

1. Configure the business glossary to define business concepts consistently

1. Try breaking the complex question into several steps

Q23: How can I improve query accuracy?

1. Enrich data cards: add accurate business descriptions for tables and fields

1. Configure the glossary: define your company's standard business terms

1. Run data discovery: establish relationships between tables

1. Refine your questions: be specific, clear, and include a time range

6. Errors and Exceptions

Q24: I see an error message when logging out — is that normal?

In some versions, a "Missing Authorization token"-style message may occasionally appear when logging out. This happens because some background requests are still in flight while the login state is being cleared.

It does not affect the logout result or data security, so it can be ignored safely. Newer versions have optimized the logout flow.

Q25: Query results differ from another system?

1. Confirm you are using the same time range, aggregation logic, and filters

1. Check whether the data card has been refreshed to the latest table structure

1. If you are still in doubt, describe the problem to your administrator for help

Q26: LLM calls are failing?

1. Make sure the API Key is configured correctly

1. Check whether the network can reach the LLM provider

1. If a proxy is required, ensure LLM_BASE_URL points to the correct proxy address

1. Check the backend logs for the specific error

7. Other Questions

Q27: How do I contact technical support?

• See the troubleshooting guide

• Submit a GitHub Issue: https://github.com/stepll2026/OntiCards/issues

Q28: Can I customize the logo and theme?

Yes, the logo and theme can be customized by modifying the frontend code.

To be added: detailed customization documentation.

Q29: Is multi-language supported?

The current version primarily supports a Chinese interface.

Planned: internationalization will be provided in a future release.

Q30: Is there an online demo I can try?

---

If you cannot find the answer to your question in this FAQ, feel free to submit an Issue and we will respond as soon as possible.