Tipo de Arquivo

Aplica-se a: Databricks Runtime 18 LTS e acima

info

Beta

Este recurso está em Beta. Os administradores do Workspace podem controlar o acesso a este recurso na página Pré-visualizações . Consulte Gerenciar prévias do Databricks.

FileType é o tipo PySpark para o tipo SQL FILE, uma referência a um arquivo não estruturado e seus metadados. Use-o para declarar parâmetros FILE e tipos de retorno em funções definidas pelo usuário (UDFs) do Python. Em Python, um valor FILE é um objeto FileRef, que mantém os metadados do arquivo e lê seus bytes.

Para a referência de tipo SQL e visão geral conceitual, consulte tipoFILE e tipo FILE e dados não estruturados. Para exemplos de UDF de processamento de arquivos, consulte Processar arquivos com UDFs.

nota

O tipo FILE não é compatível com notebooks serverless. É compatível com Notebooks anexados a Databricks SQL Serverless warehouse.

Importar

Python

from pyspark.sql.types import FileType, FileRef

Tipo de Arquivo

FileType é uma subclasse de pyspark.sql.types.DataType. Utilize-o como o tipo de parâmetro ou de retorno de um UDF, ou como um tipo de campo em um esquema.

FileType não especifica MANAGED ou EXTERNAL. Esses qualificadores se aplicam apenas a uma coluna de tabela FILE, em que a coluna determina se uma referência é armazenada como gerenciada ou externa. Um UDF transmite e retorna referências FILE, e a coluna de destino decide como cada referência é armazenada ao gravar o resultado em uma tabela.

Você pode usar FileType das seguintes maneiras, que também se aplicam a UDFs SQL e Scala e a procedimentos armazenados SQL:

• Como um tipo de nível superior.
• Aninhado dentro de um StructType ou de um ArrayType.
• Como o tipo de valor de um MapType, mas não como uma key MapType.
• Dentro de um VariantType, mas apenas para arquivos externos.

Quando uma query retorna uma coluna FILE para Python, seja dentro de um UDF ou por meio de DataFrame.collect(), cada valor é um FileRef.

FileRef

Um(a) FileRef é o valor Python para um(a) FILE. Ele mantém os metadados do arquivo e possui métodos para ler os bytes do arquivo e criar novas referências.

Atributos

Atributo	Tipo	Descrição
uri	str	O URI do arquivo. Sempre definido.
offset	int	Um offset no arquivo, em bytes.
size	int	O tamanho do arquivo em bytes.
content_type	str	O tipo MIME do arquivo, quando conhecido.
checksum	str	Um token de integridade para os bytes do arquivo, no formato <algorithm>:<digest>. Para os algoritmos reconhecidos, consulte Checksums.

Atributo	Tipo	Descrição
uri	str	O URI do arquivo. Sempre definido.
offset	int	Um offset no arquivo, em bytes.
size	int	O tamanho do arquivo em bytes.
content_type	str	O tipo MIME do arquivo, quando conhecido.
checksum	str	Um token de integridade para os bytes do arquivo, no formato <algorithm>:<digest>. Para os algoritmos reconhecidos, consulte Checksums.

Métodos

Método	Descrição
as_local_file()	Retorna um pathlib.Path para o arquivo. Passe o resultado para qualquer biblioteca que aceite um caminho. Disponível no compute do Databricks (notebooks e workers de UDF). Não disponível em um cliente Databricks Connect, como uma IDE ou aplicativo local que faz a execução do seu código fora do compute do Databricks. [[ ## completed ##]]
open()	Abre o arquivo para leitura binária e retorna um objeto de arquivo. O chamador o fecha. Tem o mesmo requisito de compute que as_local_file().
from_bytes(content, path=None, content_type=None)	Método de classe. Faz upload de content (um valor bytes) para o caminho do volume do Unity Catalog fornecido por path e retorna um FileRef. Falha se um arquivo já existir no caminho de destino. Suportado apenas dentro de uma UDF.
from_local_file(local_file, path=None, content_type=None)	Método de classe. Faz upload de um arquivo local para um volume do Unity Catalog e retorna um FileRef. Os parâmetros path e content_type se comportam como em from_bytes. Suportado apenas dentro de uma UDF.

Método	Descrição
as_local_file()	Retorna um pathlib.Path para o arquivo. Passe o resultado para qualquer biblioteca que aceite um caminho. Disponível no compute do Databricks (notebooks e workers de UDF). Não disponível em um cliente Databricks Connect, como uma IDE ou aplicativo local que faz a execução do seu código fora do compute do Databricks. [[ ## completed ##]]
open()	Abre o arquivo para leitura binária e retorna um objeto de arquivo. O chamador o fecha. Tem o mesmo requisito de compute que as_local_file().
from_bytes(content, path=None, content_type=None)	Método de classe. Faz upload de content (um valor bytes) para o caminho do volume do Unity Catalog fornecido por path e retorna um FileRef. Falha se um arquivo já existir no caminho de destino. Suportado apenas dentro de uma UDF.
from_local_file(local_file, path=None, content_type=None)	Método de classe. Faz upload de um arquivo local para um volume do Unity Catalog e retorna um FileRef. Os parâmetros path e content_type se comportam como em from_bytes. Suportado apenas dentro de uma UDF.

Exemplo

No código a seguir, uma UDF escalar recebe um valor FILE como um FileRef, abre a imagem e retorna suas dimensões:

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()

Para mais exemplos de UDF de processamento de arquivos, incluindo a geração de arquivos com uma UDTF, consulte Processar arquivos com UDFs. Para a criação geral de UDF, consulte Funções escalares definidas pelo usuário (UDF) em Python e Funções de tabela definidas pelo usuário (UDF) em Python.

Limitações

O uso de FileType no PySpark tem as seguintes limitações:

• O PySpark não oferece suporte à declaração de colunas de tabela FILE MANAGED ou FILE EXTERNAL nem à ingestão de arquivos em massa. Use SQL para essas operações. O PySpark oferece suporte apenas a FILE, como FileType, em UDFs e leituras de arquivo.
• as_local_file() e open() exigem acesso no lado do cluster, portanto, não estão disponíveis em um cliente Databricks Connect. Em vez disso, chame-os em um UDF ou no compute de cluster.
• Para from_bytes e from_local_file, as UDFs Python inferem content_type a partir da extensão do caminho, enquanto as UDFs Scala a inferem a partir dos magic bytes do arquivo.
• Não há suporte para retornar um FileRef de uma UDF que grava em uma coluna FILE MANAGED.

Recursos relacionados

• FILE Tipo
• Tipo de ARQUIVO e dados não estruturados
• Processar arquivos com UDFs
• Funções escalares definidas pelo usuário (UDFs) em Python
• Funções de tabela definidas pelo usuário (UDTFs) do Python
• Ingerir arquivos como o tipo FILE