For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Blog
DocsAPI Reference
DocsAPI Reference
    • AIStore
    • Documentation
  • Core Documentation
    • In-depth Overview
    • Terminology and core abstractions
    • Getting Started
    • Networking model
    • Buckets: design, operations, namespaces, and system buckets
    • Observability overview
    • CLI overview
    • Production deployment
    • Technical Blog
  • APIs, SDKs, and Compatibility
    • Go API
    • Python SDK
    • PyPI package
    • Python SDK reference guide
    • PyTorch integration
    • TensorFlow integration
    • HTTP API reference
    • curl examples
    • Easy URL
    • S3 compatibility
    • s3cmd quick start
    • Presigned S3 requests
    • Boto3 support
  • Command-Line Interface
    • CLI overview
    • ais help
    • CLI reference guide
    • Bucket operations
    • Cluster and remote-cluster management
    • Storage and mountpath management
    • Monitoring and ais show
    • Downloads
    • Jobs
    • Authentication and access control
    • Configuration via CLI
    • ETL CLI
    • Distributed shuffle CLI
    • ML / get-batch CLI
    • GCP credentials
    • TLS certificate management
  • Storage and Data Management
    • Storage services
    • Buckets: design, operations, namespaces, and system buckets
    • Native Bucket Inventory (NBI)
    • Backend providers
    • On-disk layout
    • Virtual directories
    • System files
    • Evicting remote buckets and cached data
  • Cluster Operations
    • Node lifecycle: maintenance, shutdown, decommission
    • Global rebalance
    • Resilver
    • AIS in Containerized Environments
    • Highly available control plane
    • Information Center (IC)
    • Out-of-band updates
    • Troubleshooting
  • Configuration and Security
    • Configuration
    • Environment variables
    • Feature flags
    • AuthN and access control
    • Authentication validation
    • HTTPS and certificates
    • Switching a cluster to HTTPS
  • ETL and Advanced Workflows
    • ETL overview
    • ETL CLI docs
    • ETL Python SDK examples
    • Custom transformers
    • ETL Python webserver SDK
    • ETL Go webserver package
    • Archives: read, write, and list
    • Distributed shuffle (dsort)
    • Initial sharding utility (ishard)
    • Downloader
    • Blob Downloader
    • Batch object retrieval (get-batch)
    • Batch operations
    • Tools and utilities
    • Extended actions (xactions)
  • Observability, Monitoring, and Performance
    • Observability overview
    • Monitoring with CLI
    • Logs
    • Prometheus integration
    • Metrics reference
    • Grafana dashboards
    • Kubernetes monitoring
    • Distributed tracing
    • Monitoring get-batch
    • AIS load generator (aisloader)
    • Benchmarking AIStore
    • Performance tuning and testing
    • Performance monitoring via CLI
    • Rate limiting
    • Checksumming
    • Filesystem Health Checker (FSHC)
    • Traffic patterns
  • Networking
    • Networking: multi-homing, network separation, IPv6
    • HTTPS configuration
    • Switching to HTTPS
    • Idle connections
    • MessagePack protocol
  • Deployment
    • AIStore on Kubernetes
    • Kubernetes Operator
    • Ansible playbooks
    • Helm charts
    • Deployment monitoring
    • Docker
  • Developer Resources
    • Development guide
    • aisnode command line
    • Build tags
  • Object and Bucket Naming
    • Unicode and special symbols in object and bucket names
    • Extremely long object names
Blog
NVIDIANVIDIA
Developer-friendly docs for your API
Privacy Policy | Your Privacy Choices | Terms of Service | Accessibility | Corporate Policies | Product Security | Contact

Copyright © 2026, NVIDIA Corporation.

LogoLogoAIStore
On this page
  • Table of Contents
  • Example: Using S3-Compatible API
  • Example: Using Native API
  • Features
  • References
Object and Bucket Naming

Extremely long object names

||View as Markdown|
Previous

Unicode and special symbols in object and bucket names

AIStore fully supports extremely long object names through both its native API and S3-compatible API. This flexibility allows for complex naming schemes, deeply nested directory structures, and detailed metadata encoding within object names.

Table of Contents

  • Example: Using S3-Compatible API
  • Example: Using Native API
  • Features
  • References

Example: Using S3-Compatible API

1#
2# 1. Generate a 1024-character random string as our object name
3#
4$ export longname=$(tr -dc 'A-Za-z0-9' < /dev/urandom | head -c 1024)
5
6#
7# 2. Upload a file with the extremely long name via S3 API
8#
9$ s3cmd put README.md s3://mybucket/$longname
10
11upload: 'README.md' -> 's3://nnn/vB4yvlo5gh6XWXDa6vR9K6klxqxP7upf94ert8ncT5a8GJ5BPCQSvK0Jc1Jxyp9U8Ek643yFJ9MFFAdwv8TP7UynvGWvUI94nRwkpil9zpgNFxbEja237kklSwiVc9DulCLDXF25YwBFWuHINNVvU27fMy56l4vgoxyNhdKYRg4L45Bq5gyluRFSgMIuhOk3xcQqAIG62g4DB0Tex5q8Ap0JOOHIlm3jNBYVf2QcFVVBOZefsQeggyMjya1NVsTmDaYLRK0oUR970FV8BAWHo05yQW4S11FkPmAy8WbsaQqKtmO2qjJlnnflZ3ItE1Nt13Tb4ZPdVzm5Ev5DQiUGgHb9kgLXa43gsIy1sc1mWbB5PkDVoKpOHCXNaHsjKXBZ0JlvoGYh7PrJ5GhMcsxjbZqccoBsSe0u7tPesn4Zfvvx754VRmBD1W8MzQel2YmoDRLj3k2992odyWxp0zke68PpulRuLZIGQGSecSOivfyouqMz2YQ7lWl5hod0qGVN4VZTtCgSaScntOmpy1aAYDxNDm5uI601JtMIHMpXMIxyndYPAel0PH4HzFQ4dBiQDERWogoHRN4eU1vflZFpOesdyxIYhcR6VgZI9JFDdKlAZwzSv136UJ876lD4I1DEqGL03dLmEsitgn2uNE515Fa3srEbeb5KMWDQ2dfTUPr6NJEqvPZrObFJdRgrk2eWeajFWjl7TtxwgyjuqMye320R3z11SAaVoOa66As4ZHGz7YsDo3lSfdyFA2tFdvLIVvLEzpKWhoZyV8NATTuWYfDKotJU7LlvfDfXqsq25A6ycMYcGQn6i3n74Xo1Xpd8Ah88jWF8KCVviLr929Qy5UJTAQAwPUMFedW5ckrWPPX4Lc1Z7j7F0Zhf6vvKdgTX7WtzqFT4OmrLtbMXiSVSAUL3NELa9sc4DRScZvfpT11UMnAz0n8X8vjnaFUDPmwRuEcaO99tPN8g7fpLiMJYQXv1VCRzJlkrmipwCqc275mcvUOkBEx189DJ3Sq0zwIi'  [1 of 1]
12 17242 of 17242   100% in    0s     8.86 MB/s  done
13upload: 'README.md' -> 's3://nnn/vB4yvlo5gh6XWXDa6vR9K6klxqxP7upf94ert8ncT5a8GJ5BPCQSvK0Jc1Jxyp9U8Ek643yFJ9MFFAdwv8TP7UynvGWvUI94nRwkpil9zpgNFxbEja237kklSwiVc9DulCLDXF25YwBFWuHINNVvU27fMy56l4vgoxyNhdKYRg4L45Bq5gyluRFSgMIuhOk3xcQqAIG62g4DB0Tex5q8Ap0JOOHIlm3jNBYVf2QcFVVBOZefsQeggyMjya1NVsTmDaYLRK0oUR970FV8BAWHo05yQW4S11FkPmAy8WbsaQqKtmO2qjJlnnflZ3ItE1Nt13Tb4ZPdVzm5Ev5DQiUGgHb9kgLXa43gsIy1sc1mWbB5PkDVoKpOHCXNaHsjKXBZ0JlvoGYh7PrJ5GhMcsxjbZqccoBsSe0u7tPesn4Zfvvx754VRmBD1W8MzQel2YmoDRLj3k2992odyWxp0zke68PpulRuLZIGQGSecSOivfyouqMz2YQ7lWl5hod0qGVN4VZTtCgSaScntOmpy1aAYDxNDm5uI601JtMIHMpXMIxyndYPAel0PH4HzFQ4dBiQDERWogoHRN4eU1vflZFpOesdyxIYhcR6VgZI9JFDdKlAZwzSv136UJ876lD4I1DEqGL03dLmEsitgn2uNE515Fa3srEbeb5KMWDQ2dfTUPr6NJEqvPZrObFJdRgrk2eWeajFWjl7TtxwgyjuqMye320R3z11SAaVoOa66As4ZHGz7YsDo3lSfdyFA2tFdvLIVvLEzpKWhoZyV8NATTuWYfDKotJU7LlvfDfXqsq25A6ycMYcGQn6i3n74Xo1Xpd8Ah88jWF8KCVviLr929Qy5UJTAQAwPUMFedW5ckrWPPX4Lc1Z7j7F0Zhf6vvKdgTX7WtzqFT4OmrLtbMXiSVSAUL3NELa9sc4DRScZvfpT11UMnAz0n8X8vjnaFUDPmwRuEcaO99tPN8g7fpLiMJYQXv1VCRzJlkrmipwCqc275mcvUOkBEx189DJ3Sq0zwIi'  [1 of 1]
14 17242 of 17242   100% in    0s    16.28 MB/s  done
15
16#
17# 3. List objects in the bucket
18#
19$ s3cmd ls s3://mybucket
202025-04-09 09:45        17242  s3://mybucket/LWGKqSkJdRsN5ZoxKw3Z3TmfS7qM5OM54aPloJOTmaYzmswzf4LB5ARrWsyD3BXZsItCaKY5lTJzCb3XlAoBMdbymH875g7XCDgNYcqSEvLi14E3cTeQe4bzD1lrn3ZdDRubQuR3oCHHMRH6ny8R75s09rcVz1jlEiXLYuna7VmdCVVTFqUG6uDBV1pQZ8onAmOVm49Osr5GNWdjp0jP5e2AMpXodyzvlI3UISCu6QJYahDsmbMzCkeDqjm0qcX9xB9wdN28WijpDdgNB40SOsR21BOKhubgXxpKDP39Aj3oQaKz3zjXKNkkIvrtLLmq41qEKgbSWc8iZk2IZOjzFJcmi4G42mEy8t5eagKHylCyuxVfz72B9fRv7MaNJllLHKrZernHjQhHXu3RgoAdibx5qsoKTmZYTxeZNsBWn8IBE4oGrsGc99t638ETO7NBEnPW9Ibgxv0bpdwmfEwgzsvxmVrlAySuoBBuvYmL7KbY0PPBHtDe4gVfYYAg15Ba
212025-04-09 09:54        17242  s3://mybucket/vB4yvlo5gh6XWXDa6vR9K6klxqxP7upf94ert8ncT5a8GJ5BPCQSvK0Jc1Jxyp9U8Ek643yFJ9MFFAdwv8TP7UynvGWvUI94nRwkpil9zpgNFxbEja237kklSwiVc9DulCLDXF25YwBFWuHINNVvU27fMy56l4vgoxyNhdKYRg4L45Bq5gyluRFSgMIuhOk3xcQqAIG62g4DB0Tex5q8Ap0JOOHIlm3jNBYVf2QcFVVBOZefsQeggyMjya1NVsTmDaYLRK0oUR970FV8BAWHo05yQW4S11FkPmAy8WbsaQqKtmO2qjJlnnflZ3ItE1Nt13Tb4ZPdVzm5Ev5DQiUGgHb9kgLXa43gsIy1sc1mWbB5PkDVoKpOHCXNaHsjKXBZ0JlvoGYh7PrJ5GhMcsxjbZqccoBsSe0u7tPesn4Zfvvx754VRmBD1W8MzQel2YmoDRLj3k2992odyWxp0zke68PpulRuLZIGQGSecSOivfyouqMz2YQ7lWl5hod0qGVN4VZTtCgSaScntOmpy1aAYDxNDm5uI601JtMIHMpXMIxyndYPAel0PH4HzFQ4dBiQDERWogoHRN4eU1vflZFpOesdyxIYhcR6VgZI9JFDdKlAZwzSv136UJ876lD4I1DEqGL03dLmEsitgn2uNE515Fa3srEbeb5KMWDQ2dfTUPr6NJEqvPZrObFJdRgrk2eWeajFWjl7TtxwgyjuqMye320R3z11SAaVoOa66As4ZHGz7YsDo3lSfdyFA2tFdvLIVvLEzpKWhoZyV8NATTuWYfDKotJU7LlvfDfXqsq25A6ycMYcGQn6i3n74Xo1Xpd8Ah88jWF8KCVviLr929Qy5UJTAQAwPUMFedW5ckrWPPX4Lc1Z7j7F0Zhf6vvKdgTX7WtzqFT4OmrLtbMXiSVSAUL3NELa9sc4DRScZvfpT11UMnAz0n8X8vjnaFUDPmwRuEcaO99tPN8g7fpLiMJYQXv1VCRzJlkrmipwCqc275mcvUOkBEx189DJ3Sq0zwIi
22
23#
24# 4. Get object metadata
25#
26$ s3cmd info s3://mybucket/$longname
27s3://nnn/vB4yvlo5gh6XWXDa6vR9K6klxqxP7upf94ert8ncT5a8GJ5BPCQSvK0Jc1Jxyp9U8Ek643yFJ9MFFAdwv8TP7UynvGWvUI94nRwkpil9zpgNFxbEja237kklSwiVc9DulCLDXF25YwBFWuHINNVvU27fMy56l4vgoxyNhdKYRg4L45Bq5gyluRFSgMIuhOk3xcQqAIG62g4DB0Tex5q8Ap0JOOHIlm3jNBYVf2QcFVVBOZefsQeggyMjya1NVsTmDaYLRK0oUR970FV8BAWHo05yQW4S11FkPmAy8WbsaQqKtmO2qjJlnnflZ3ItE1Nt13Tb4ZPdVzm5Ev5DQiUGgHb9kgLXa43gsIy1sc1mWbB5PkDVoKpOHCXNaHsjKXBZ0JlvoGYh7PrJ5GhMcsxjbZqccoBsSe0u7tPesn4Zfvvx754VRmBD1W8MzQel2YmoDRLj3k2992odyWxp0zke68PpulRuLZIGQGSecSOivfyouqMz2YQ7lWl5hod0qGVN4VZTtCgSaScntOmpy1aAYDxNDm5uI601JtMIHMpXMIxyndYPAel0PH4HzFQ4dBiQDERWogoHRN4eU1vflZFpOesdyxIYhcR6VgZI9JFDdKlAZwzSv136UJ876lD4I1DEqGL03dLmEsitgn2uNE515Fa3srEbeb5KMWDQ2dfTUPr6NJEqvPZrObFJdRgrk2eWeajFWjl7TtxwgyjuqMye320R3z11SAaVoOa66As4ZHGz7YsDo3lSfdyFA2tFdvLIVvLEzpKWhoZyV8NATTuWYfDKotJU7LlvfDfXqsq25A6ycMYcGQn6i3n74Xo1Xpd8Ah88jWF8KCVviLr929Qy5UJTAQAwPUMFedW5ckrWPPX4Lc1Z7j7F0Zhf6vvKdgTX7WtzqFT4OmrLtbMXiSVSAUL3NELa9sc4DRScZvfpT11UMnAz0n8X8vjnaFUDPmwRuEcaO99tPN8g7fpLiMJYQXv1VCRzJlkrmipwCqc275mcvUOkBEx189DJ3Sq0zwIi (object):
28   File size: 17242
29   Last mod:  Wed, 09 Apr 2025 09:54:30 GMT
30   MIME type: none
31   Storage:   STANDARD
32   MD5 sum:   2940e853a9b97580df19b76d10d3ea31
33   SSE:       none
34   Policy:    none
35   CORS:      none
36   ACL:       none
37   x-amz-meta-ais-cksum-type: md5
38   x-amz-meta-ais-cksum-val: 2940e853a9b97580df19b76d10d3ea31
39
40#
41# 5. Confirm MD5
42#
43$ md5sum README.md
442940e853a9b97580df19b76d10d3ea31  README.md
45
46#
47# 6. Download the object with the long name
48#
49$ s3cmd get s3://mybucket/$longname ./downloaded-file.md

Example: Using Native API

1#
2# 1. Upload a file with an extremely long object name
3#
4$ ais put README.md mybucket/$longname
5
6#
7# 2. List objects with a specific prefix
8#
9$ ais ls ais://mybucket/$longname
10PROPERTY         VALUE
11atime            09 Apr 25 09:54 EDT
12checksum         md5[2940e853a9b97580...]
13name             ais://nnn/.x9a4cca2da6fffe8cd9aa78442e66f1c2f722caa28293024ddcce5b25c162586c
14size             16.84KiB
15
16#
17# 3. Get object properties
18#
19$ ais show mybucket/$longname
20
21#
22# 4. Download the object
23#
24$ ais get mybucket/$longname ./downloaded-file.md

Features

  • No Practical Length Limits: AIStore can handle object names that are 4000+ characters long
  • Dual API Support: Access the same capabilities through either native API or S3 API
  • Full Path Preservation: Deep directory structures are maintained as-is
  • Consistent Performance: Long object names do not impact operational speed

References

  • No limitations principle