Oracle BFILENAME() 函数使用指南

Oracle BFILENAME() 是一个内置函数，它返回一个指向服务器操作系统文件系统中外部二进制文件（BFILE）的定位器。

通过 BFILENAME() 函数，数据库可以在不把实际文件二进制数据导入到表内部存储的情况下，引用外部服务器目录下的图片、视频、PDF 或结构化大文件。

Oracle BFILENAME() 语法

这里是 Oracle BFILENAME() 函数的标准语法：

BFILENAME('directory', 'filename')

参数

directory

必需的。一个目录对象（Directory Object）的名称。该目录必须事先在数据库中使用 CREATE DIRECTORY 语句创建，并赋予当前用户读取权限。目录名称在 Oracle 数据字典中通常以大写形式保存，若传入小写可能会因找不到目录对象而引发错误。

filename

必需的。服务器物理文件系统中的目标文件名，包括文件扩展名（例如 'report_2026.pdf' 或 'logo.png'）。

返回值

Oracle BFILENAME() 函数返回一个指向外部文件的 BFILE 定位器。

  • 如果 directory 或 filename 中任意一个参数为 NULL，BFILENAME() 将返回 NULL。
  • 注意：BFILENAME() 函数本身不会在调用瞬间验证物理操作系统中文件是否存在；文件存在性校验通常在后续通过 DBMS_LOB.FILEEXISTS() 访问或读取 LOB 定位器时进行。

Oracle BFILENAME() 示例

这里有几个展示 Oracle BFILENAME() 函数常见用法的示例。

基本用法：向包含 BFILE 列的表插入文件指针

假设我们已经创建了一个逻辑目录对象 MEDIA_DIR 并拥有相关权限：

-- 1. 创建目录对象并授权（通常由 DBA 执行）
CREATE OR REPLACE DIRECTORY MEDIA_DIR AS '/var/data/oracle/media';
GRANT READ ON DIRECTORY MEDIA_DIR TO public;

-- 2. 创建包含 BFILE 字段的员工多媒体表
CREATE TABLE employee_media (
    emp_id     NUMBER PRIMARY KEY,
    emp_name   VARCHAR2(50),
    photo_file BFILE
);

-- 3. 使用 BFILENAME 函数插入外部照片定位器
INSERT INTO employee_media (emp_id, emp_name, photo_file)
VALUES (101, '张伟', BFILENAME('MEDIA_DIR', 'emp_101.jpg'));

COMMIT;

查询该记录的定位器信息：

SELECT 
    emp_id, 
    emp_name, 
    BFILENAME('MEDIA_DIR', 'emp_101.jpg') AS photo_locator
FROM employee_media
WHERE emp_id = 101;

输出：

    EMP_ID EMP_NAME             PHOTO_LOCATOR
---------- -------------------- --------------------------------------------------
       101 张伟                 0000100000000001000000000000000000000000

配合 DBMS_LOB 检查外部文件是否存在

通过 BFILENAME 获取定位器后，通常会结合 DBMS_LOB 包检查底层操作系统中文件是否真实存在：

SET SERVEROUTPUT ON;
DECLARE
    v_bfile BFILE;
    v_exists NUMBER;
BEGIN
    v_bfile := BFILENAME('MEDIA_DIR', 'emp_101.jpg');
    v_exists := DBMS_LOB.FILEEXISTS(v_bfile);

    IF v_exists = 1 THEN
        DBMS_OUTPUT.PUT_LINE('文件存在于指定的服务器目录中。');
    ELSE
        DBMS_OUTPUT.PUT_LINE('文件不存在或目录权限不足。');
    END IF;
END;
/

输出：

文件存在于指定的服务器目录中。

NULL 参数处理

如果传入任意 NULL 参数，BFILENAME() 均返回 NULL：

SET NULL 'NULL';
SELECT
    BFILENAME('MEDIA_DIR', NULL) AS res_null_file,
    BFILENAME(NULL, 'doc.pdf') AS res_null_dir
FROM dual;

输出：

RES_NULL_FILE  RES_NULL_DIR
-------------- --------------
NULL           NULL

结论

  • BFILENAME() 是在 Oracle 中管理只读外部文件（BFILE）的关键入口函数。
  • 目录对象参数必须使用大写（例如 'MEDIA_DIR'），除非创建目录时使用了被双引号包裹的区分大小写的标识符。
  • BFILE 存储的是文件定位指针而非文件数据本身，使用时需保证数据库系统用户（操作系统层面如 oracle 用户）对目标目录具有读权限。