Introduction
The Char field is one of the most fundamental field types in the Odoo data model. If you have ever looked at a contact name, a product reference, or a sales order note, you have interacted with a Char field without necessarily knowing it.
Understanding how this field type works matters whether you are a business user configuring forms in Odoo Studio, a developer writing custom modules, or a consultant helping a client design their Odoo environment.
It looks simple on the surface, but there are several properties and behaviors worth knowing to use it well and avoid common mistakes. This guide walks through everything from what the field stores and how it behaves in the interface, to creating and customizing it, along with real business use cases.
What is the Char Field in Odoo
In the Odoo ORM, the Char field is designed to store short text strings. It maps to a VARCHAR or TEXT column in PostgreSQL, depending on whether you define a size limit.
From the user perspective, a Char field appears as a single-line text input in forms and as a plain text column in list views. It is the standard choice for storing names, codes, references, identifiers, and any other short piece of text that fits on one line.
Here is how it looks in a Python model definition:
from odoo import fields, models
class SaleOrder(models.Model):
_inherit = 'sale.order'
customer_po_reference = fields.Char(
string='Customer PO Reference',
size=64,
index=True,
)The string parameter sets the label shown in the interface. The size parameter, which is optional, limits the number of characters. The index parameter creates a database index for faster searches.
In Odoo Studio, this same field is called a Text field (single line). When created through Studio, it gets an x_studio_ prefix automatically. When created via code or the XML-RPC API, you choose the technical name yourself.
How the Field Works
When you define a Char field in Odoo, the framework handles the column creation in the database automatically during module installation or upgrade. There is no need to write SQL migrations manually.
In the database, Char fields without a size limit are stored as TEXT. Those with a size parameter use VARCHAR(n). PostgreSQL treats both types efficiently, so the difference is mostly about enforcing a length constraint rather than a major performance distinction.
Key Field Attributes
Here are the most important properties of a Char field in the Odoo framework:
- size: Maximum number of characters. Omit this and there is no length limit at the database level.
- translate: When set to
True, the field value can be translated per language. Useful in multilingual deployments. - required: Makes the field mandatory in the interface and at the model level.
- default: Sets an automatic default value when new records are created.
- index: Creates a database index for faster filtering and searching on that field.
- compute: Links a Python method that computes the field value dynamically, useful for derived or concatenated values.
- store: When combined with
compute, controls whether the computed value is persisted in the database. - copy: Controls whether the field value is copied when duplicating a record. Defaults to
True.
How It Appears in Views
In form views, a Char field renders as a standard <input type="text"> element. In list views, it displays as plain text. In search views, it supports filters using contains, equals, and starts-with operators out of the box.
You can also combine a Char field with widgets in the view to change how it appears. For example, the email widget turns a Char field into a clickable email link, and the url widget makes it open in a new browser tab.
Interaction with the Odoo ORM
From a developer perspective, reading and writing Char fields works like any other field in the Odoo ORM. You access the value directly on the record object, and the framework handles sanitization and validation based on the field definition. There are no complex transformations involved, which is part of what makes the Char field so practical for everyday use in Odoo development.
Business Use Cases
The Char field appears in almost every corner of an Odoo implementation. Here are five real-world examples from common business workflows.
CRM: Customer Reference Numbers
Many companies assign internal reference numbers to their clients. A Char field on the res.partner model can store this code, making it searchable from the customer list and visible on sale orders and invoices. Sales teams can quickly pull up the right account without confusion when multiple clients share similar names.
Sales: Purchase Order References
When customers send purchase orders, they include a PO number that needs to appear on invoices and delivery documents. The native client_order_ref field on sale.order is a Char field. It flows through to the invoice automatically, reducing back-and-forth with the customer about missing references.
Inventory: Internal Product References
The default_code field on product.template is a native Char field in Odoo. It stores the internal reference used across warehouses, barcode scanners, and purchase orders. Keeping this field clean and consistent is one of the most common data quality priorities in inventory implementations.
Accounting: Tax and Registration Numbers
VAT numbers, tax IDs, and company registration numbers are stored as Char fields on partner records. These values automatically appear on customer invoices and vendor bills when properly configured. For companies operating across multiple countries, having this data reliably stored in one place saves a lot of manual correction work.
HR: Employee Identifiers and Badge Codes
HR teams frequently need to store employee ID numbers, badge codes, or identifiers from external payroll or access control systems. A Char field on the employee model makes it easy to link Odoo records with other business tools without needing a full integration from day one.
Creating or Customizing the Char Field
There are three main ways to add a Char field to an Odoo model, depending on your technical setup and deployment approach.
Using Odoo Studio (No Code)
Odoo Studio is the built-in low-code customization tool. To add a Char field without writing any code:
- Open Odoo Studio from the main menu.
- Navigate to the form where you want the field.
- Drag a Text field (single line) from the sidebar onto the form.
- Set the label, required status, and optionally a size limit in the field properties panel.
- Save and close Studio.
Studio automatically creates the field with an x_studio_ prefix and adds it to the form view. No database migration is needed on your side.
Using Python in a Custom Module
For developers building Odoo modules, Char fields are defined in Python model files. This is the recommended approach for any customization that needs to be version-controlled and deployed across multiple environments:
from odoo import fields, models
class ResPartner(models.Model):
_inherit = 'res.partner'
x_erp_customer_id = fields.Char(
string='ERP Customer ID',
size=32,
index=True,
copy=False,
)After adding the field to the model, you also need to add it to the relevant view XML file so it appears in the interface. Odoo handles the database column creation when you install or upgrade the module.
Using the XML-RPC API
If you are managing Odoo customizations programmatically, for example as part of a deployment pipeline or a remote configuration notebook, you can create Char fields via the XML-RPC API:
field_id = models.execute_kw(
ODOO_DB, uid, ODOO_API_KEY,
'ir.model.fields', 'create',
[{
'name': 'x_custom_reference',
'field_description': 'Custom Reference',
'model_id': model_id,
'ttype': 'char',
'size': 64,
'state': 'manual',
}]
)The state: manual value tells Odoo this field was created manually (not by a module), which is the correct setting for fields created through Studio or the API. This is how Dasolo manages remote field creation for clients as part of automated configuration scripts.
Best Practices
1. Set a size when you know the maximum length
If the field stores ISO country codes, phone numbers, or fixed-length identifiers, define a size. This communicates intent to anyone reading the model and prevents accidental data entry errors. A field meant to store a two-letter country code should not silently accept a 500-character string.
2. Add an index for fields you search frequently
If users regularly filter or search records by a Char field, such as a customer code or order reference, set index=True. On tables with tens of thousands of records, this can make the difference between a one-second search and a ten-second wait.
3. Use translate=True for multilingual content
If your Odoo instance serves users in multiple languages and a field contains text that varies by language, enable translation. This matters for product names, job positions, or any field whose value users in different regions would expect to see in their own language.
4. Give fields clear and consistent technical names
In custom modules, name fields descriptively. A field called x_customer_erp_id is far more maintainable than x_field1. If using Studio, rename the field in the properties panel before deploying it. Technical names cannot easily be changed later once data is stored.
5. Use compute for derived references
Char fields can be computed dynamically. For example, a reference that combines a year and a sequence number can be built as a computed Char field. With store=True, the value is saved in the database and can be used in search filters and reports, while the computation logic remains centralized in one method.
Common Pitfalls
No size limit leaves the door open for bad data
Without a size constraint, users can paste entire paragraphs into a reference field. This is a real problem when the value later appears on printed documents or is sent to external systems with strict character limits. Always define a reasonable size for fields where length matters.
Missing indexes on frequently searched fields
Without an index, filtering by a Char field on a large table is a full table scan. Many teams only discover this problem after their database grows to a meaningful size. If a field is used regularly in list view filters or search bars, add the index from the start.
Confusing Char with Text field
The Char field is for short single-line text. The Text field is for longer multi-line content. Using a Char field for addresses, notes, or descriptions leads to a poor user experience, since the input will not wrap or allow line breaks. If the content could realistically span multiple sentences, use a Text field instead.
Forgetting translate on multilingual fields
In companies operating across multiple countries, missing the translate=True option on a user-facing field means all language users see the same value. This can cause confusion on customer-facing documents where the field content should adapt to the document language.
Using Char for data that should be a Selection or relation
If a field always holds one of a limited set of values, like a category, a status, or a country, it should be a Selection field or a Many2one relation, not a Char field. Using Char for this creates inconsistent values across records and makes filtering and reporting unreliable. Free-text fields invite typos and variations that break grouping and analysis.
FAQ
What is the difference between a Char field and a Text field in Odoo?
A Char field stores short single-line text and renders as a text input in forms. A Text field stores longer multi-line content and renders as a resizable textarea. Use Char for names, codes, and references. Use Text for descriptions, notes, and anything users might write several sentences for.
Can I limit the number of characters stored in a Char field?
Yes. Use the size parameter when defining the field in Python, for example fields.Char(size=64). In Odoo Studio, you can set this limit in the field properties panel. If no size is set, the field has no enforced length limit at the database level.
How do I make a Char field appear in the search bar?
Add the field to the search view of the model. In Studio, enable the search option in the field properties. In code, add <field name="your_char_field"/> inside the <search> view definition in your XML. Once added, users can filter records by that field directly from the search bar.
Can I store numbers in a Char field?
Technically yes, but it is not recommended for values that need calculation or numeric comparison. Use Integer or Float fields for quantities and amounts. Char is appropriate for strings that happen to contain digits, such as ZIP codes, phone numbers, IBAN numbers, or serial numbers, where the value is treated as text rather than a number.
How do I create a computed Char field that also stores its value?
Define the field with compute='_compute_my_field' and store=True. Write the compute method using @api.depends() to declare which other fields trigger the recomputation. With store=True, Odoo saves the computed value in the database, making it available in searches, filters, and exports without recalculating on every read.
Conclusion
The Char field is deceptively simple. Most people interact with dozens of them every day in Odoo without thinking about it. But when you are building or customizing an Odoo system, understanding its properties, its database behavior, and when to use it versus other field types makes a real difference in the quality of your data model.
Whether you are adding a customer reference through Odoo Studio, defining a field in a custom Python module, or creating fields programmatically via the API, the patterns described in this guide will help you get it right the first time.
A well-designed data model built on the right field types is one of the most important foundations of a successful Odoo implementation. The Char field is a small piece of that puzzle, but it is one worth understanding properly.
At Dasolo, we help companies implement, customize, and optimize Odoo across all departments. Whether you need help designing a clean data model, adding custom fields to your workflows, or building a full Odoo module from scratch, our team is here to help. Reach out to us and let's talk about your Odoo project.