finetype

Semantische Typklassifikation — erkennt 251 Datentypen (E-Mails, URLs, Datumsangaben, UUIDs, Währungen usw.) aus Rohzeichenketten

Maintainer: hughcameron

Installation und Laden

INSTALL finetype FROM community;
LOAD finetype;

Beispiel

-- Profile every column of a table: one row per column, with the detected
-- semantic type, model confidence, and recommended DuckDB storage type.
D CREATE TABLE people AS SELECT * FROM (VALUES
    ('jane.doe@company.co.uk', '+44 20 7946 0958', {'city': 'London'}),
    ('john.smith@example.org', '0117 496 0123',    {'city': 'Bristol'}),
    ('not-an-email',           'not-a-phone',       {'city': 'Leeds'})
  ) AS t(email, phone, addr);

D SELECT * FROM ft_profile('people');
┌─────────────┬──────────────────────────────────────────────────────────────────────────────────┬────────────────────┬─────────────┐
│ column_name │                                       type                                       │     confidence     │ duckdb_type │
│   varchar   │                                     varchar                                      │       double       │   varchar   │
├─────────────┼──────────────────────────────────────────────────────────────────────────────────┼────────────────────┼─────────────┤
│ addr        │ nested STRUCT(city VARCHAR) column — unnest / to_json / extract before profiling │               NULL │ NULL        │
│ email       │ identity.person.email                                                            │ 0.5915254950523376 │ VARCHAR     │
│ phone       │ identity.person.phone_number                                                     │                0.5 │ VARCHAR     │
└─────────────┴──────────────────────────────────────────────────────────────────────────────────┴────────────────────┴─────────────┘
-- (addr is a nested STRUCT column: instead of silently mis-classifying it,
--  ft_profile emits a flatten hint in the type column and leaves
--  confidence / duckdb_type NULL. See the nested-column note below.)

-- Validate a table against a JSON Schema (note the top-level "properties"
-- key): one row per column, counting how many values the schema rejects.
D SELECT * FROM ft_validate('people',
    '{"properties":{"email":{"type":"string","pattern":"^[^@]+@[^@]+\\.[^@]+$"},
                    "phone":{"type":"string","pattern":"^\\+?[0-9().+ -]{7,}$"}}}');
┌─────────────┬───────┬─────────┬───────────────────────────────────────────────────────────────────────────────────┐
│ column_name │ total │ rejects │                                  sample_message                                   │
│   varchar   │ int64 │  int64  │                                      varchar                                      │
├─────────────┼───────┼─────────┼───────────────────────────────────────────────────────────────────────────────────┤
│ addr        │  NULL │    NULL │ nested STRUCT(city VARCHAR) column — unnest / to_json / extract before validating │
│ email       │     3 │       1 │ "not-an-email" does not match "^[^@]+@[^@]+\.[^@]+$"                              │
│ phone       │     3 │       1 │ "not-a-phone" does not match "^\+?[0-9().+ -]{7,}$"                               │
└─────────────┴───────┴─────────┴───────────────────────────────────────────────────────────────────────────────────┘

-- Classify a single value (per-value, no column context)
D SELECT ft_infer('https://example.com') AS detected_type;
┌──────────────────────────┐
│      detected_type       │
│         varchar          │
├──────────────────────────┤
│ technology.internet.url  │
└──────────────────────────┘

Über finetype

FineType ist ein semantischer Typklassifikator, der 251 Datentypen aus Rohzeichenketten erkennt. Ein mehrzweigiges neuronales Netz kennzeichnet jeden Wert und ordnet ihn einer dreistufigen Taxonomie zu: domain.category.type.

FineType ist spaltenorientiert: Seine Genauigkeit entsteht, weil es eine ganze Spalte auf einmal sieht; die primäre Oberfläche sind daher die Tabellenverben ft_profile / ft_validate unten. Skalarfunktionen pro Wert gibt es ebenfalls für Ad-hoc-Klassifikation, aber ein einzelner Wert, der sich normalerweise auf seine Spaltennachbarn zur Disambiguierung stützt (eine bloße UUID, eine Telefonnummer), wird weniger zuverlässig klassifiziert als derselbe Wert im Spaltenkontext.

Tabellenverben

Diese nehmen eine Tabelle (oder eine LIST von Spaltenwerten) und liefern eine Zeile pro Spalte — die natürliche Körnung für Profiling und Validierung.

ft_profile(table_name VARCHAR)

Profiliert jede Spalte einer Tabelle. Liefert (column_name, type, confidence, duckdb_type), eine Zeile pro Spalte. Die Tabelle wird als Zeichenkettenliteral benannt; FineType greift in den Katalog, um ihre Spalten zu lesen.

SELECT * FROM ft_profile('people');

Verschachtelte STRUCT-/LIST-Spalten werden abgesichert, nicht still verworfen: statt sie durch eine Werteklassifikation zu zwingen, die sie falsch melden würde, liefert ft_profile einen Flatten-Hinweis in der Spalte type (confidence und duckdb_type bleiben NULL). Flatten Sie die Spalte zuerst, wenn Sie sie typisieren möchten.

ft_validate(table_name VARCHAR, schema_json VARCHAR)

Validiert die Spalten einer Tabelle gegen ein JSON Schema. Liefert eine Zeile pro validierter Spalte mit der Anzahl geprüfter Werte, der Ablehnungszahl und einer beispielhaften Ablehnungsmeldung. Das Schema kann inline, über getvariable oder aus einer Datei geliefert werden — ein bloßer Pfad wird für Sie gelesen, während eine Zeichenkette, die mit { beginnt, unverändert verwendet wird.

Das JSON Schema ist unter einem Top-Level-Objekt properties nach Spalte geschlüsselt.

Die geprüften Constraints sind pattern, minLength, maxLength, enum, type und required. Laut JSON-Schema-Spezifikation ist format eine Annotation und keine Assertion: {"format":"email"} beschreibt die Spalte und lehnt nichts ab. Verwenden Sie pattern, wenn Werte als Ablehnungen gezählt werden sollen.

-- inline
SELECT * FROM ft_validate('people', '{"properties":{"email":{"type":"string","pattern":"^[^@]+@[^@]+\\.[^@]+$"}}}');

-- via a variable, when the schema is long enough to want a name
SET VARIABLE email_schema = '{"properties":{"email":{"type":"string","minLength":6}}}';
SELECT * FROM ft_validate('people', getvariable('email_schema'));

Aggregatfunktion

ft_profile(value VARCHAR[, header VARCHAR]) → STRUCT(type VARCHAR, confidence DOUBLE, duckdb_type VARCHAR)

Profiliert eine Spalte direkt als Aggregat über ihre Werte — nützlich, wenn die Spalte bereits vorliegt und Sie keine Tabelle benennen möchten. Sie steht in einem SELECT statt in einem FROM und liefert ein STRUCT statt einer Zeile pro Spalte.

Übergeben Sie den Spaltennamen als zweites Argument. FineType nutzt die Überschrift als Evidenz; die Zweargumentform reproduziert daher die Antwort von ft_profile(table); ohne sie können dieselben Werte auf einem anderen Typ landen.

SELECT ft_profile(email, 'email') FROM people;
-- {'type': identity.person.email, 'confidence': 0.5915254950523376, 'duckdb_type': VARCHAR}

SELECT ft_profile(email) FROM people;  -- no header: less evidence, different answer
-- {'type': representation.text.plain_text, 'confidence': 0.6070796251296997, 'duckdb_type': VARCHAR}

Weil es ein Aggregat ist, kann es kein list(...) aufnehmen — das Verschachteln eines Aggregats in einem anderen ist ein Binder-Fehler. Verwenden Sie unten ft_detail(values LIST), wenn Sie die Werte bereits als Liste haben.

Skalarfunktionen

Klassifikation pro Wert, ein Wert nach dem anderen. Am stärksten bei isoliert eindeutigen Werten (URLs, ISO-Datumsangaben, wohlgeformte E-Mails, IP-Adressen).

ft_infer(value VARCHAR) → VARCHAR

Klassifiziert einen einzelnen Wert. Liefert das vollständige semantische Typ-Label.

SELECT ft_infer('https://example.com');  -- technology.internet.url
SELECT ft_infer('2024-01-15');           -- datetime.date.iso
SELECT ft_infer('true');                 -- representation.boolean.terms

ft_detail(value VARCHAR) → VARCHAR

Klassifiziert mit vollständigen Details. Liefert JSON mit Typ, Konfidenz (0.0–1.0), dem empfohlenen DuckDB-Typ, der Anzahl gesehener Samples, dem Disambiguierungspfad und der Stimmenkarte pro Label.

SELECT ft_detail('192.168.1.1');
-- {"type": "technology.internet.ip_v4", "confidence": 0.829, "duckdb_type": "INET", ...}

ft_cast(value VARCHAR) → VARCHAR

Normalisiert einen Wert für sicheres TRY_CAST() auf den erkannten DuckDB-Typ. Behandelt Datumsformat- Konvertierung (US/EU → ISO), Boolesche Normalisierung, UUID-Kleinschreibung und numerische Bereinigung.

SELECT ft_cast('01/15/2024');  -- 2024-01-15 (US date → ISO)

ft_validate_text(value VARCHAR, schema_json VARCHAR) → STRUCT(valid BOOLEAN, "constraint" VARCHAR, message VARCHAR)

Validiert einen einzelnen Wert gegen ein JSON-Schema-Fragment. Liefert ein Struct: valid ist true, wenn der Wert konform ist (constraint und message sind NULL); bei Fehler ist valid false und constraint / message nennen das fehlschlagende Schlüsselwort und den Grund. Das ist die Engine pro Zelle, die das Tabellenverb ft_validate über jede Spalte ausführt.

SELECT ft_validate_text('not-an-email', '{"type":"string","pattern":"^[^@]+@[^@]+\\.[^@]+$"}');
-- {'valid': false, 'constraint': pattern, 'message': '"not-an-email" does not match "^[^@]+@[^@]+\.[^@]+$"'}

ft_unpack(json VARCHAR) → VARCHAR

Klassifiziert rekursiv jeden Skalarwert in einem JSON-Dokument. Liefert annotiertes JSON mit Typ, Konfidenz, empfohlenem DuckDB-Typ und Originalwert für jedes Feld.

ft_version() → VARCHAR

Liefert die Versionszeichenkette der Erweiterung.

Aliase. Die früheren Skalarnamen ohne Präfix (finetype, finetype_detail, finetype_cast, finetype_unpack, finetype_validate, finetype_version) bleiben als Aliase der ft_-Skalare registriert, sodass bestehender Code weiter funktioniert. Neuer Code sollte die ft_-Namen verwenden.

Typ-Taxonomie

244 Typen in 7 Domänen:

• container: JSON, XML, CSV, Arrays, Schlüssel-Wert (11 Typen)
• datetime: Daten, Zeiten, Zeitstempel, Epochen, Dauern, Offsets (86 Typen)
• finance: Währungen, Buchhaltung, Marktidentifikatoren, Transaktionen (28 Typen)
• geography: Koordinaten, Orte, Adressen, Verkehr (25 Typen)
• identity: Namen, E-Mails, Telefone, Zahlungen, Medizin (33 Typen)
• representation: Boolesche Werte, Zahlen, Text, Dateien, Wissenschaft (32 Typen)
• technology: URLs, IPs, UUIDs, Versionen, Codes (29 Typen)

Weitere Informationen finden Sie in der FineType-Dokumentation.

Hinzugefügte Funktionen

Überladene Funktionen

Diese Erweiterung fügt keine Funktionsüberladungen hinzu.

Hinzugefügte Typen

Diese Erweiterung fügt keine Typen hinzu.

Hinzugefügte Einstellungen

Diese Erweiterung fügt keine Einstellungen hinzu.