Einleitung
Binary-Felder wirken unspektakulär, sind aber in jeder ernsthaften Odoo‑Installation allgegenwärtig. Sobald ein Nutzer einen Vertrag hochlädt, ein Datenblatt an ein Produkt hängt oder ein Firmenlogo speichert, arbeitet hinter den Kulissen ein Binary‑Feld. Wer die Speicherung, den Aufbewahrungsort und die Grenzen dieser Feldart kennt, trifft bessere Entscheidungen beim Erstellen von Formularen, beim Erweitern von Modellen oder beim Entwerfen von Berichten.
Dieser Leitfaden erklärt, welche Daten ein Binary‑Feld hält, wie der Attachment‑Modus Speicher und Performance beeinflusst, wie Sie das Feld per Studio oder Python anlegen und anpassen und welche praktischen Anwendungsfälle sich in CRM, HR, Lagerhaltung und Co. ergeben.
Was ist das Binary-Feld in Odoo?
Im Odoo‑ORM repräsentiert fields.Binary binäre Inhalte: also Dateien, Bilder oder Dokumente, die Nutzer an Datensätze anhängen. In Formularen sieht der Anwender typischerweise einen Upload‑Button; nach dem Anhang dient derselbe Button zum Herunterladen der Datei mit einem Klick.
Der wichtigste technische Punkt ist, wo die Daten tatsächlich abgelegt werden. In aktuellen Odoo‑Versionen arbeitet das Binary‑Feld standardmäßig im Attachment‑Modus: Die eigentlichen Bytes landen in der ir.attachment‑Tabelle und im Filestore des Servers. Die Spalte im eigentlichen Modell enthält nur noch einen Verweis auf den Attachment‑Eintrag. Das hält die Haupttabellen schlank und erlaubt Odoo, Dateien effizient zu verwalten.
In Odoo Studio heißt das Binary‑Feld File im Feldkatalog und erscheint als einfaches Upload/Download‑Steuerelement im Formular. Für Bilder bietet Odoo zusätzlich fields.Image an — diese Spezialform kümmert sich um Größenbegrenzung und Vorschaubilder. Darauf gehe ich weiter unten explizit ein.
So könnte die Definition eines Binary‑Felds in einem Python‑Modell aussehen:
from odoo import fields, models
class ResPartner(models.Model):
_inherit = 'res.partner'
x_signed_contract = fields.Binary(
string='Signed Contract',
attachment=True,
)
x_signed_contract_filename = fields.Char(
string='Signed Contract Filename',
)Achten Sie auf das begleitende Char‑Feld x_signed_contract_filename. Es ist gängige Praxis, einem Binary‑Feld ein _filename‑Feld zur Seite zu stellen, damit Odoo den ursprünglichen Dateinamen speichern und beim Download anzeigen kann. Ohne dieses Feld landen Downloads oft unter einem generischen Namen.
Wie das Feld technisch funktioniert
Wenn Sie ein Binary‑Feld im Modell definieren, erstellt Odoo die benötigte Datenbankspalte automatisch beim Installieren oder Aktualisieren des Moduls. Sie müssen keine SQL‑Manipulationen durchführen.
Speichermodi
Der Parameter attachment bestimmt, wo die Datei‑Bytes tatsächlich abgelegt werden:
- attachment=True (empfohlen): Der Inhalt liegt in
ir.attachment, verbunden mit Modellname und Datensatz‑ID; die Modellspalte hält nur einen Verweis. Das verringert die Größe der Modelltabellen und nutzt Odos Filestore. - attachment=False: Die Base64‑kodierten Bytes werden direkt in der Spalte des Modells gespeichert. Das lässt Tabellen schnell anwachsen und verlangsamt Abfragen. Vermeiden Sie diesen Modus für alles, was größer als ein kleines Vorschaubild ist.
Datenformat
Binary‑Felder arbeiten mit Base64. Beim Lesen über ORM oder XML‑RPC erhalten Sie einen Base64‑String; beim Schreiben müssen Sie ebenfalls einen Base64‑kodierten String übergeben.
In der Praxis heißt das: vor dem Schreiben kodieren, nach dem Lesen dekodieren:
import base64
# Writing a file to a Binary field
with open('document.pdf', 'rb') as f:
encoded = base64.b64encode(f.read()).decode('utf-8')
record.write({'x_signed_contract': encoded})
# Reading a file from a Binary field
raw_bytes = base64.b64decode(record.x_signed_contract)Wichtige Feldattribute
Diese Attribute sind bei Binary‑Feldern besonders relevant:
- attachment: Boolean. Legt fest, ob in
ir.attachment(True) oder direkt in der Spalte (False) gespeichert wird. In aktuellen Odoo‑Versionen ist True Standard. - string: Bezeichnung, die in der UI angezeigt wird.
- required: Macht das Feld beim Speichern obligatorisch.
- compute: Verknüpft eine Python‑Methode, um den Wert dynamisch zu erzeugen (z. B. PDF‑Generierung on‑the‑fly).
- store: Speichert berechnete Werte in der DB, wenn mit
computeverwendet. - groups: Beschränkt Sichtbarkeit und Bearbeitung auf bestimmte Nutzergruppen — wichtig für sensible Dokumente.
- copy: Steuert, ob der Wert beim Kopieren eines Datensatzes dupliziert wird; Verhalten hängt von Attachment‑Mode und Odoo‑Version ab.
Die fields.Image‑Spezialisierung
Seit Odoo 13 gibt es fields.Image, ein spezielles Subtyp von Binary für Bilder. Es skaliert automatisiert auf maximale Dimensionen, erzeugt optionale Thumbnails und zeigt im Formular eine Vorschau an. Für Produktbilder, Portraits oder Logos ist fields.Image die bessere Wahl als ein generisches Binary‑Feld: geringere Uploads, bessere UX und weniger Speicherverbrauch.
Darstellung in Views
Im Formular ist das Standard‑Widget für Binary‑Felder ein Upload/Download‑Knopf. Setzen Sie das image‑Widget für eine Thumbnail‑Vorschau bei Bildern. In Listenansichten sollten Binary‑Felder normalerweise nicht direkt angezeigt werden — das Laden kompletter Dateien für alle sichtbaren Zeilen erzeugt unnötigen Datentransfer. Besser: ein Icon oder ein berechnetes Boolean‑Feld, das anzeigt, ob eine Datei vorhanden ist.
Typische Geschäftsszenarien
Fünf praxisnahe Beispiele zeigen, wie Binary‑Felder im Tagesgeschäft genutzt werden.
CRM: Unterzeichnete Vereinbarungen auf Kundenprofilen ablegen
Vertriebsmitarbeiter profitieren davon, unterschriebene NDAs oder Verträge direkt am Kunden- oder Lead‑Datensatz abzulegen. Ein Binary‑Feld auf res.partner oder crm.lead bringt relevante Dokumente an genau den Ort, an dem sie im Verkaufsgespräch gebraucht werden — ohne separates DMS und ohne zusätzlichen Kontextwechsel.
HR: Mitarbeiterunterlagen zentral speichern
Personalabteilungen speichern Personalausweise, Arbeitserlaubnisse, unterschriebene Arbeitsverträge oder Zertifikate häufig direkt im Mitarbeiterdatensatz (hr.employee). Mit dem groups‑Attribut lassen sich Zugriffsrechte so einschränken, dass nur berechtigte HR‑Manager kritische Dokumente einsehen können, während andere Führungskräfte nur die restlichen Mitarbeiterinformationen sehen.
Lager/Produktion: Produktdatenblätter und Sicherheitsdatenblätter
Für technische Produkte gehören PDF‑Spezifikationen und Sicherheitsdatenblätter zur Routine. Ein Binary‑Feld am product.template stellt diese Dokumente dem Einkauf und Lagerpersonal direkt am Produkt zur Verfügung. Für Fertigung und Distribution ist das eine der häufigsten Anpassungsanforderungen — leicht umsetzbar mit Studio oder einem kleinen Modul.
Vertrieb: Firmenstempel oder Signaturbilder für Druckvorlagen
Wenn Angebote oder Auftragsbestätigungen gestempelt oder mit einer autorisierten Unterschrift versehen werden sollen, eignet sich ein fields.Image auf res.company. Das Bild lässt sich in QWeb‑Vorlagen referenzieren, sodass Ausdrucke automatisch das gewünschte Signatur‑ oder Stempelbild enthalten — zeitsparend und fehlerarm bei hohem Dokumentenvolumen.
Buchhaltung: Belegabbildungen an Spesen anhängen
Spesenabrechnungen verlangen meist den Scan des Belegs als Nachweis. In Standard‑Odoo ist das Attachment‑System vorhanden, doch in kundenspezifischen Modellen oder bei Drittintegrationen bietet ein Binary‑Feld eine saubere Möglichkeit, den Beleg direkt am Belegdatensatz zu speichern und in Genehmigungsprozessen zu verwenden.
Anlegen und Anpassen des Binary-Felds
Es gibt drei gängige Wege, ein Binary‑Feld in ein Modell einzufügen — je nach Kenntnisstand und benötigter Revisionskontrolle.
Mit Odoo Studio (No‑Code)
Odoo Studio ist das Low‑Code‑Werkzeug. So fügen Sie ein Binary‑Feld ohne Entwicklertätigkeit hinzu:
- Studio aus dem Hauptmenü öffnen.
- Zum gewünschten Formular navigieren.
- Ein File‑Feld aus dem Feldkatalog per Drag & Drop ins Formular ziehen.
- Bezeichnung und Sichtbarkeitsregeln im Eigenschaftenfenster einstellen.
- Speichern und Studio schließen.
Studio legt das Feld mit dem Präfix x_studio_ an und verwendet standardmäßig Attachment‑Modus. Keine DB‑Konfiguration nötig — ideal, wenn Business‑User schnell Dateiuploads in Formulare einbauen wollen.
Per Python in einem Custom‑Modul
Für versionierte, wiederholbare Anpassungen ist die Definition in einem Modul via Python der Standardweg. Empfehlenswert für produktive, teamorientierte Odoo‑Projekte:
from odoo import fields, models
class HrEmployee(models.Model):
_inherit = 'hr.employee'
x_id_document = fields.Binary(
string='ID Document',
attachment=True,
groups='hr.group_hr_user',
)
x_id_document_filename = fields.Char(
string='ID Document Filename',
)Nach Modelländerung fügen Sie das Feld in die Formularansicht ein (XML) mit dem Widget binary und dem Attribut filename, das auf das begleitende Char‑Feld zeigt. Odoo erstellt die DB‑Spalte beim Modulinstall oder -update automatisch. Diese Vorgehensweise funktioniert in Odoo.sh, On‑Premise und allen verbreiteten Deployment‑Szenarien.
Über die XML‑RPC‑API
Wenn Felder programmgesteuert angelegt werden sollen — z. B. in einem Deploy‑Script oder einer Konfigurationsroutine — geht das per XML‑RPC:
field_id = models.execute_kw(
ODOO_DB, uid, ODOO_API_KEY,
'ir.model.fields', 'create',
[{
'name': 'x_custom_document',
'field_description': 'Custom Document',
'model_id': model_id,
'ttype': 'binary',
'state': 'manual',
}]
)Der Wert state: 'manual' signalisiert, dass das Feld manuell erstellt wurde und nicht Teil eines Moduls ist. Felder, die so erzeugt werden, nutzen in aktuellen Odoo‑Versionen standardmäßig Attachment‑Modus — praktisch für automatisierte Konfigurationen und Remote‑Deployments.
Best Practices
1. Immer attachment=True verwenden
Ausnahmefälle abgesehen: Speichern Sie Dateiinhalte nicht in der Modellspalte. Attachment‑Modus hält Tabellen schlank, vermeidet langsame Abfragen und setzt den Filestore effizient ein. Für alles, was größer als ein Vorschaubild ist, ist Attachment‑Mode praktisch Pflicht.
2. Binary‑Felder mit einem filename‑Char paaren
Immer eine begleitende _filename Char‑Spalte anlegen. Ohne sie verlieren Downloads ihren ursprünglichen Namen und landen als generische Datei. Ein kleiner Schritt mit großer UX‑Wirkung.
3. Für Bilder fields.Image nutzen
Produktfotos, Portraits oder Logos gehören in fields.Image, nicht in ein generisches Binary. Image limitiert Dimensionen, liefert Thumbnails und reduziert unnötigen Speicherverbrauch — saubere Modellgestaltung zahlt sich aus.
4. Zugriff mit groups einschränken
Sensible Dokumente wie Mitarbeiterakten oder Verträge gehören hinter Gruppenrechte. Das groups‑Attribut schützt vor unbefugtem Zugriff und unterstützt Compliance‑Anforderungen.
5. Base64‑Encoding in Code korrekt handhaben
Beim programmatischen Lesen und Schreiben müssen Sie Base64‑Kodierung explizit behandeln: base64.b64encode(file_bytes).decode('utf-8') zum Schreiben und base64.b64decode(field_value) zum Lesen. Viele Integrationsfehler entstehen genau hier, wenn Formate fälschlich angenommen werden.
Häufige Fehlerquellen
Warum attachment=False für große Dateien problematisch ist
Wenn Sie Dateien direkt in einer Modellspalte speichern, blähen Sie Ihre PostgreSQL‑Tabelle schnell auf. Einige Dutzend PDFs mit attachment=False können Hundert megabyte in eine Tabelle bringen und jede Abfrage verlangsamen. Das ist eine der gravierendsten Fehlkonfigurationen in Odoo‑Datenbanken; eine spätere Migration in Attachment‑Mode ist aufwendig und erfordert sorgfältige Planung.
Das Vergessen des filename‑Felds
Ohne Begleit‑Char‑Feld erhalten Benutzer beim Download oft neutrale Dateinamen — ein kleines, aber lästiges UX‑Problem. Das Beifügen des Filename‑Felds dauert Sekunden und sollte Standard bei allen nutzerzugänglichen Binary‑Feldern sein.
Binary und Image verwechseln
Ein Binary‑Feld für Bilder zu verwenden führt dazu, dass Nutzer große Bilddateien hochladen, die Formulare verlangsamen und Speicher verbrauchen. Umgekehrt erzeugt fields.Image Fehler, wenn Sie PDF‑Dateien damit speichern wollen. Fazit: Feldtyp immer an den erwarteten Inhalt anpassen.
Binary‑Felder in Listenansichten einbinden
Binary‑Felder in Listansichten führen dazu, dass Odoo für jede sichtbare Zeile komplette Datei‑Inhalte lädt — bei 50 Zeilen schnell mehrere Megabyte Transfer. Verwenden Sie stattdessen ein berechnetes Boolean‑Feld oder ein Icon, um die Anwesenheit einer Datei anzuzeigen.
Nicht auf False prüfen, bevor man verarbeitet
Fehlt ein Wert, liefert ein Binary‑Feld in Python False, nicht einen leeren String oder leere Bytes. Ein direktes Dekodieren ohne Prüfung führt zu TypeError. Sichern Sie deshalb mit: if record.x_document: data = base64.b64decode(record.x_document). Das gilt für Compute‑Methoden, Server‑Aktionen und Integrationen.
Fazit
Das Binary‑Feld ist zwar technisch simpel, aber ein zentraler Baustein im Odoo‑Datenmodell. Es integriert Dateispeicherung nahtlos in UI, Attachment‑System und Zugriffssteuerung.
Merken Sie sich die Kerngewohnheiten: Attachment‑Modus verwenden, Dateinamen‑Feld ergänzen, fields.Image für Bilder wählen, sensible Dokumente gruppenbasiert schützen und Base64‑Handling sauber implementieren. Diese Praktiken vermeiden die häufigsten Probleme, bevor sie in Produktion auftreten.
Egal ob Sie ein Upload‑Feld per Studio hinzufügen, ein Modul in Python entwickeln oder Felder via ORM/XML‑RPC verwalten: Wenn Binary‑Felder von Anfang an korrekt angelegt sind, erhalten Sie eine robustere und wartungsfreundlichere Odoo‑Lösung.
Bei Dasolo unterstützen wir Unternehmen bei der Implementierung, Anpassung und Optimierung von Odoo in allen Fachbereichen. Ob Datenmodellberatung, maßgeschneiderte Datei‑Workflows oder komplette Modulentwicklung — unser Team begleitet Sie gern. Kontaktieren Sie uns und sprechen wir über Ihr Odoo‑Projekt.