Type de fichier

S'applique à : Databricks Runtime 18 LTS et versions ultérieures

info

Bêta

Cette fonctionnalité est en bêta. Les administrateurs de Workspace peuvent contrôler l'accès à cette fonctionnalité à partir de la page Aperçus . Voir Gérer les prévisualisations Databricks.

FileType est le type PySpark pour le type SQL FILE, une référence à un fichier non structuré et à ses métadonnées. Utilisez-le pour déclarer les parameter FILE et les types de retour dans les fonctions définies par l'utilisateur (UDF) Python. En Python, une valeur FILE est un objet FileRef, qui contient les métadonnées du fichier et lit ses octets.

Pour la référence du type SQL et une vue d'ensemble conceptuelle, voir typeFILE et type FILE et données non structurées. Pour des exemples d'UDF de traitement de fichiers, voir Traiter des fichiers avec des UDF.

remarque

Le type FILE n'est pas pris en charge sur les notebooks serverless. Il est pris en charge sur les Notebooks attachés à des Databricks SQL warehouse Serverless.

Importer

Python

from pyspark.sql.types import FileType, FileRef

Type de fichier

FileType est une sous-classe de pyspark.sql.types.DataType. Utilisez-le comme type de parameter ou de retour d’une UDF, ou comme type de champ dans un schéma. [[ ## completed ##]]

FileType ne spécifie pas MANAGED ou EXTERNAL. Ces qualificateurs s’appliquent uniquement à une colonne de table FILE, où la colonne détermine si une référence est stockée en tant que gérée ou externe. Une UDF transmet et renvoie des références FILE, et la colonne cible détermine la manière dont chaque référence est stockée lorsque vous écrivez le résultat dans une table.

Vous pouvez utiliser FileType des manières suivantes, qui s’appliquent également aux UDF SQL et Scala ainsi qu’aux procédures stockées SQL :

• En tant que type de niveau supérieur.
• Imbriqué dans un StructType ou un ArrayType.
• En tant que type de valeur d'un MapType, mais pas en tant que clé MapType.
• À l’intérieur d’un VariantType, mais uniquement pour les fichiers externes.

Lorsqu’une query renvoie une colonne FILE à Python, que ce soit à l’intérieur d’une UDF ou via DataFrame.collect(), chaque valeur est un FileRef.

FileRef

Un FileRef est la valeur Python pour un FILE. Il contient les métadonnées du fichier et dispose de méthodes pour lire les octets du fichier et créer de nouvelles références.

Attributs

Attribut	Type	Description
uri	str	L'URI du fichier. Toujours défini.
offset	int	Un décalage dans le fichier, en octets.
size	int	La taille du fichier en octets.
content_type	str	Le type MIME du fichier, lorsqu'il est connu.
checksum	str	Un jeton d'intégrité pour les octets du fichier, sous la forme <algorithm>:<digest>. Pour les algorithmes reconnus, consultez Checksums.

Attribut	Type	Description
uri	str	L'URI du fichier. Toujours défini.
offset	int	Un décalage dans le fichier, en octets.
size	int	La taille du fichier en octets.
content_type	str	Le type MIME du fichier, lorsqu'il est connu.
checksum	str	Un jeton d'intégrité pour les octets du fichier, sous la forme <algorithm>:<digest>. Pour les algorithmes reconnus, consultez Checksums.

Méthodes

Méthode	Description
as_local_file()	Renvoie un pathlib.Path vers le fichier. Transmettez le résultat à toute bibliothèque acceptant un chemin d’accès. Disponible sur le compute Databricks (Notebooks et Worker UDF). Non disponible sur un client Databricks Connect, tel qu’un IDE ou une application locale qui exécute votre code en dehors du compute Databricks.
open()	Ouvre le fichier pour une lecture binaire et renvoie un objet fichier. L'appelant le ferme. A la même exigence de compute que as_local_file().
from_bytes(content, path=None, content_type=None)	Méthode de classe. Upload content (une valeur bytes) vers le chemin de volume Unity Catalog indiqué par path et renvoie un FileRef. Échoue si un fichier existe déjà au chemin cible. Pris en charge uniquement à l'intérieur d'une UDF.
from_local_file(local_file, path=None, content_type=None)	Méthode de classe. Effectue l’upload d’un fichier local vers un volume Unity Catalog et renvoie un FileRef. Les paramètres path et content_type se comportent comme dans from_bytes. Pris en charge uniquement à l’intérieur d’une UDF.

Méthode	Description
as_local_file()	Renvoie un pathlib.Path vers le fichier. Transmettez le résultat à toute bibliothèque acceptant un chemin d’accès. Disponible sur le compute Databricks (Notebooks et Worker UDF). Non disponible sur un client Databricks Connect, tel qu’un IDE ou une application locale qui exécute votre code en dehors du compute Databricks.
open()	Ouvre le fichier pour une lecture binaire et renvoie un objet fichier. L'appelant le ferme. A la même exigence de compute que as_local_file().
from_bytes(content, path=None, content_type=None)	Méthode de classe. Upload content (une valeur bytes) vers le chemin de volume Unity Catalog indiqué par path et renvoie un FileRef. Échoue si un fichier existe déjà au chemin cible. Pris en charge uniquement à l'intérieur d'une UDF.
from_local_file(local_file, path=None, content_type=None)	Méthode de classe. Effectue l’upload d’un fichier local vers un volume Unity Catalog et renvoie un FileRef. Les paramètres path et content_type se comportent comme dans from_bytes. Pris en charge uniquement à l’intérieur d’une UDF.

Exemple

Dans le code suivant, une UDF scalaire reçoit une valeur FILE en tant que FileRef, ouvre l’image et renvoie ses dimensions :

Python

from pyspark.sql.functions import col, udf
from pyspark.sql.types import StringType
from PIL import Image

@udf(returnType=StringType())
def image_resolution(file):
    with Image.open(file.as_local_file()) as img:
        return f"{img.width}x{img.height}"

spark.read.table("images").select(image_resolution(col("photo"))).display()

Pour plus d’exemples d’UDF de traitement de fichiers, y compris la génération de fichiers avec une UDTF, consultez Traiter des fichiers avec des UDF. Pour la création générale d’UDF, consultez les fonctions scalaires définies par l’utilisateur (UDF) Python et les fonctions de table définies par l’utilisateur (UDTF) Python.

Limitations

L'utilisation de FileType dans PySpark présente les limitations suivantes :

• PySpark ne prend pas en charge la déclaration de colonnes de table FILE MANAGED ou FILE EXTERNAL, ni l'ingestion de fichiers en masse. Utilisez SQL pour ces Opérations. PySpark prend uniquement en charge FILE, en tant que FileType, dans les UDF et les lectures de fichiers.
• as_local_file() et open() nécessitent un accès côté cluster, ils ne sont donc pas disponibles sur un client Databricks Connect. Appelez-les plutôt dans une UDF ou sur un compute de cluster.
• Pour from_bytes et from_local_file, les UDF Python déduisent content_type à partir de l'extension du chemin, tandis que les UDF Scala le déduisent à partir des magic bytes du fichier.
• Le renvoi d'un FileRef à partir d'une UDF qui écrit dans une colonne FILE MANAGED n'est pas pris en charge.

Ressources connexes

• FILE Type
• Type FILE et données non structurées
• Traiter des fichiers avec des UDF
• Fonctions scalaires définies par l’utilisateur (UDF) Python
• Fonctions de table définies par l'utilisateur (UDTF) en Python
• Ingérer les fichiers en tant que type FILE