SMB (Server Message Block) is a network file sharing protocol that provides shared access to files, printers, and serial ports. It is commonly used in Windows environments for network shares but is also supported on Linux (via Samba) and macOS.
The SMB Data Connector enables federated SQL query across supported file formats stored on SMB/CIFS network shares. It supports SMB 2.0, 2.1, 3.0, and 3.1.1 protocols, compatible with Windows Server file shares, Samba servers, NAS devices (Synology, QNAP, etc.), and Azure Files.
Connect to an SMB share and query Parquet files:
Query the data using SQL:
fromSpecifies the SMB server, share, and path to connect to.
Format: smb://<host>/<share>/<path>
<host>: The server hostname or IP address<share>: The share name on the server<path>: Path to a file or directory within the share (optional)When pointing to a directory, Spice loads all files within that directory recursively.
Examples:
nameThe dataset name used as the table name in SQL queries. Cannot be a reserved keyword.
params| Parameter Name | Description |
|---|---|
file_format | Required when connecting to a directory. See File Formats. |
smb_user | Username for SMB authentication. Use secrets syntax: ${secrets:smb_user}. |
smb_pass | Password for SMB authentication. Use secrets syntax: ${secrets:smb_pass}. |
smb_port | SMB server port. Default: 445. |
client_timeout | Connection timeout duration. E.g. 30s, 1m. No timeout when unset. |
hive_partitioning_enabled | Enable Hive-style partitioning from folder structure. Default: false. |
Connect to a Windows file share with domain credentials:
For Windows domain environments, include the domain in the username:
The domain can be specified as DOMAIN\user or user@domain.
When pointing to a specific file, the format is inferred from the file extension:
Configure a timeout for slow or unreliable network connections:
Connect to SMB servers running on non-standard ports:
Enable Hive-style partitioning to automatically extract partition columns from the folder structure:
Given a folder structure like:
Queries can filter on partition columns:
Load different datasets from multiple shares on the same server:
Enable local acceleration for faster repeated queries:
Acceleration is recommended for frequently queried data, as SMB operations involve network round-trips for directory listing and file reads.
For benchmark configurations with multiple related tables, use YAML anchors to avoid repeating parameters:
Spice integrates with multiple secret stores for secure credential management. Store SMB credentials in a secret store and reference them using the ${secrets:key} syntax.
For detailed information, refer to the secret stores documentation.
The SMB connector is read-only. Write operations such as put, delete, and copy are not supported.
Only username/password authentication is supported. Kerberos and NTLM ticket-based authentication are not available.
Direct network access to the SMB server is required; proxy connections are not supported. The firewall must permit SMB traffic (port 445 by default).
If connections frequently timeout, increase the client_timeout value:
Verify network connectivity to the server and check that firewall rules permit port 445.
Common causes of authentication failures:
DOMAIN\username or username@domainIf you receive "share not found" errors:
When connecting to a directory, ensure file_format is specified and matches the actual file types in the directory. Spice expects all files in a directory to have the same format.
Enable debug logging to diagnose SMB connection issues: