29:null 2a:["$","title",null,{"children":"File Attachments | ObeyMyGH | Observable"}] 2f:T4be,Open the **Data** pane by clicking the icon, in the top-right corner of the browser window. From there, click the plus sign next to **File attachments** to select a file from your desktop to attach it.30:Tafc,| Method | Description | | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | `attachment.url()` | Returns a promise to the URL at which the file may be retrieved. | | `attachment.text()` | Returns a promise to the file’s contents as a JavaScript string. | | `attachment.json()` | Returns a promise to the file’s contents, parsed as JSON into JavaScript values. | | `attachment.csv()` | Returns a promise to the file’s contents, parsed as comma-separated values (CSV) into an array. Options:
`{array = false, typed = false}` | | `attachment.tsv()` | Returns a promise to the file’s contents, parsed as tab-separated values (TSV) into an array. Options:
`{array = false, typed = false}` | | `attachment.image()` | Returns a promise to a file loaded as an Image with optional JavaScript properties. Options:
`{property: value, property: value}` | | `attachment.arrayBuffer()` | Returns a promise to the file’s contents as an ArrayBuffer. | | `attachment.stream()` | Returns a promise to a ReadableStream of the file’s contents. | | `attachment.blob()` | Returns a promise to a Blob containing the raw contents of the file. | | `attachment.sqlite()` | Returns a promise to the file loaded as a SQLite database client. | | `attachment.xlsx()` | Returns a promise to the file loaded as a Workbook. | | `attachment.xml()` | Returns a promise to an XMLDocument containing the contents of the file. | | `attachment.html()` | Returns a promise to an HTMLDocument containing the contents of the file. | | `attachment.zip()` | Returns a promise to a list of files in the ZIP archive. Files can be read from the archive. | 31:[{"id":"64d21082dcd00f21843ac22313ce443c1faa36a462afdb3c063f7cadea1c5d22a959c4aa3e89db2d7ecf2533689e0cf63659dc4058774654aae62049ecbaa940","href":"https://static.observableusercontent.com/files/64d21082dcd00f21843ac22313ce443c1faa36a462afdb3c063f7cadea1c5d22a959c4aa3e89db2d7ecf2533689e0cf63659dc4058774654aae62049ecbaa940","name":"national-archive.jpg","type":"image/jpeg","lastModified":1672868417010.172,"size":409265},{"id":"86ff47388d832e549c0661861f8107e4e65187de3333abf70f940359eac7810c611eebb7511565264f4b8b001229fd9a6832a21a421c6be3623ccbd97cbf5737","href":"https://static.observableusercontent.com/files/86ff47388d832e549c0661861f8107e4e65187de3333abf70f940359eac7810c611eebb7511565264f4b8b001229fd9a6832a21a421c6be3623ccbd97cbf5737","name":"example.json","type":"application/octet-stream","lastModified":1672868417010.172,"size":53},{"id":"09f63bb9ff086fef80717e2ea8c974f918a996d2bfa3d8773d3ae12753942c002d0dfab833d7bee1e0c9cd358cd3578c1cd0f9435595e76901508adc3964bbdc","href":"https://static.observableusercontent.com/files/09f63bb9ff086fef80717e2ea8c974f918a996d2bfa3d8773d3ae12753942c002d0dfab833d7bee1e0c9cd358cd3578c1cd0f9435595e76901508adc3964bbdc","name":"example.csv","type":"application/octet-stream","lastModified":1672868417010.172,"size":275},{"id":"a86c4f95f3ec10fd2d13544ecf6bdf49ae25066ba2e8b2ca96fddd0a831c09cd2ac0ffb441e2e6db6258648fbe267b413d71937c17b4a0d80e1822d99ba2fb0a","href":"https://static.observableusercontent.com/files/a86c4f95f3ec10fd2d13544ecf6bdf49ae25066ba2e8b2ca96fddd0a831c09cd2ac0ffb441e2e6db6258648fbe267b413d71937c17b4a0d80e1822d99ba2fb0a","name":"example.png","type":"image/png","lastModified":1672868417010.172,"size":126867},{"id":"e2a5a0ac299b53fc1016e082c7c0732d50d0dc9388d8b99adadeee40d6d1c856991c15698dcdf582a6827b411ba6d470bf7a6d28426fb8bc1cd7cc28f17199bd","href":"https://static.observableusercontent.com/files/e2a5a0ac299b53fc1016e082c7c0732d50d0dc9388d8b99adadeee40d6d1c856991c15698dcdf582a6827b411ba6d470bf7a6d28426fb8bc1cd7cc28f17199bd","name":"the-persistence-of-memory.jpg","type":"image/jpeg","lastModified":1672868417010.172,"size":179013},{"id":"1bc7c60612fed26b5376e8648f66b956192d6698e532730c148ea00491a6ff0122dc5cdf605f8d6ae209c4547176c2da042296b7665f4ace4eabda3d4500762c","href":"https://static.observableusercontent.com/files/1bc7c60612fed26b5376e8648f66b956192d6698e532730c148ea00491a6ff0122dc5cdf605f8d6ae209c4547176c2da042296b7665f4ace4eabda3d4500762c","name":"example.shp","type":"application/octet-stream","lastModified":1672868417010.172,"size":498480},{"id":"1a485a6468d79a87fe0794e1119dee719716ec2b2f91d26e04e88bc3faa739c11fca8cd3d85d2e525c4ed936a6f7b9bc1b530c4fa00df82a82fc63525ca17d9e","href":"https://static.observableusercontent.com/files/1a485a6468d79a87fe0794e1119dee719716ec2b2f91d26e04e88bc3faa739c11fca8cd3d85d2e525c4ed936a6f7b9bc1b530c4fa00df82a82fc63525ca17d9e","name":"example.pdf","type":"application/pdf","lastModified":1672868417010.172,"size":27483},{"id":"f4fd5c681574c1ff7050d59fd5fa64f7bc30d28763a6246afa5786d07181a34c07ddc47f614ce00669b69c09aabdbe77fbada74d9c06a590e8712cf19a95c1c3","href":"https://static.observableusercontent.com/files/f4fd5c681574c1ff7050d59fd5fa64f7bc30d28763a6246afa5786d07181a34c07ddc47f614ce00669b69c09aabdbe77fbada74d9c06a590e8712cf19a95c1c3","name":"sp500.csv","type":"text/csv","lastModified":1672868417010.172,"size":10213}] 2d:{"id":"da76e18a6d9a3fbd","slug":null,"title":"File Attachments","thumbnail":"9037f4259f5b5c119d6541a7176e348686caf51ffc9177f3378f27fe1bd72a26","access_level":"public","create_time":"$D2023-01-04T21:40:17.010Z","update_time":"$D2023-01-04T21:40:17.010Z","view_time":null,"first_public_time":"$D2023-01-04T21:40:17.010Z","fork":true,"stars":0,"starred":false,"owner":{"type":"team","id":"0354938a5dd10c5f","login":"obey","name":"ObeyMyGH","avatar_url":"https://avatars-next.observableusercontent.com/84c352432ac546e3e3229af582bcc15a3a78ab6da1ca97e8559b916972a1d0f1","tier":"starter_2024"},"version":970,"publish_version":null,"role":null,"authored":false,"authors":[{"type":"individual","id":"440b42ffda60d765","login":"obey","name":"ObeyMyGH","avatar_url":"https://avatars-next.observableusercontent.com/84c352432ac546e3e3229af582bcc15a3a78ab6da1ca97e8559b916972a1d0f1","tier":null}],"members":[{"type":"individual","id":"440b42ffda60d765","login":"obey","name":"ObeyMyGH","avatar_url":"https://avatars-next.observableusercontent.com/84c352432ac546e3e3229af582bcc15a3a78ab6da1ca97e8559b916972a1d0f1","tier":null,"role":"editor"}],"comments":[],"custom_thumbnail":false,"trashed":false,"subscribed":null,"forks":0,"collection":null,"type":"notebook","body":{"title":"File Attachments","cells":[{"id":260,"value":"# File Attachments\n\n

Files, IRL. Photo: [EduVolunteer/Wikimedia](https://commons.wikimedia.org/wiki/File:A_corridor_of_files_at_The_National_Archives_UK.jpg)

","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined"},{"id":847,"value":"The quickest way to work with small-ish datasets in a notebook is to attach a file. Files in Observable can be used for a variety of purposes besides data too, such as videos or images (like the one above!).","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined"},{"id":0,"value":"File attachments behave like you expect: files are private when notebooks are private, files are copied when you fork or merge, files can be reused across notebooks through imports, and you can go back in time in notebook history. And because Observable is designed for tinkering, you can even play with your local files in other people’s notebooks, then fork to upload your files and save your work.","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined"},{"id":142,"value":"(If you want to work with live data, we recommend [database clients](/@observablehq/connecting-to-databases) to talk to databases, or [secrets](/@observablehq/secrets) to talk to API servers. Observable also supports [cloud files](/@observablehq/cloud-files) for live files hosted on the Microsoft or Google cloud.)","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined"},{"id":851,"value":"### Attaching files\n\nWe offer several convenient ways to attach files.","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined"},{"id":852,"value":"While editing a cell, hit ${keys(\"Cmd-Shift-U\")} to choose a local file or files. This will automatically insert the code to reference these files at the caret, and if you own the notebook, the files will immediately start uploading.","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined"},{"id":22,"value":"$2f","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined"},{"id":82,"value":"### Using files\n\nTo use a file, first pass the file’s name to the built-in FileAttachment function from the [Observable standard library](https://github.com/observablehq/stdlib).","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined"},{"id":27,"value":"attachment = FileAttachment(\"example.json\")","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined"},{"id":658,"value":"*In these examples, all of the files are attached to this notebook. You can open the File Attachments pane and download them to inspect them and follow along, or replace them with example files of your own.*","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined"},{"id":29,"value":"Calling FileAttachment doesn’t immediately load the file—the contents are only loaded when you request them. It’s a bit like the [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch): there are async methods that return the file’s contents in different forms, such as JSON, CSV, or ArrayBuffer. You choose the appropriate method based on how you want to consume the file.","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined"},{"id":926,"value":"### FileAttachment() API\nThe `FileAttachment` API (https://github.com/observablehq/stdlib#file-attachments) provides a number of useful methods that return promises to the file’s contents in a handful of convenient forms:","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined"},{"id":967,"value":"$30","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined"},{"id":861,"value":"Here are a few examples. First, bog standard JSON.","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined"},{"id":36,"value":"json = FileAttachment(\"example.json\").json()","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined"},{"id":410,"value":"json.hello.world","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined"},{"id":382,"value":"How about comma-separated values (CSV)? We can do that. (If you want more control over parsing, load the file as text instead, and pass it to your parser of choice. Observable uses [d3-dsv](https://github.com/d3/d3-dsv).)","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined"},{"id":31,"value":"data = FileAttachment(\"example.csv\").csv()","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined"},{"id":684,"value":"data.columns // in case you’re curious","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined"},{"id":417,"value":"If our CSV is suitably formatted, meaning compatible with [d3.autoType](/@d3/d3-autotype), we can use automatic type inference to convert strings into more specific types such as numbers and dates.","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined"},{"id":415,"value":"typed = FileAttachment(\"example.csv\").csv({typed: true})","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined"},{"id":686,"value":"If you’d rather have an array of arrays and not treat the first row as the header, use the *array* option. (This can be combined with the *typed* option, too.)","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined"},{"id":689,"value":"array = FileAttachment(\"example.csv\").csv({array: true})","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined"},{"id":915,"value":"You can read ZIP (.zip) file attachments as well: see [FileAttachment.zip](https://observablehq.com/@observablehq/zip) for examples.","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined"},{"id":920,"value":"If you want to perform more complicated parsing on the rows — for instance, if there are commas in the number values — you can use a chained promise to write a custom parsing function. ","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined"},{"id":919,"value":"sp500 = FileAttachment(\"sp500.csv\").csv()\n .then(data => {\n const parseCommas = (d) => Number(d.replace(/,/g, \"\"));\n return data.map(row => ({\n Open: parseCommas(row.Open)\n }))\n })","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined"},{"id":57,"value":"How about an image? The promise resolves after the image has loaded, making this convenient for manipulating images with Canvas, or loading WebGL textures.","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined"},{"id":42,"value":"image = FileAttachment(\"example.png\").image({width: 400, style: \"border: 1px solid black\"})","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined"},{"id":554,"value":"To embed the image in Markdown or HTML literals, await it.","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined"},{"id":558,"value":"

\n ${await FileAttachment(\"the-persistence-of-memory.jpg\").image()}\n

Image: Salvador Dali

\n","pinned":true,"hidden":false,"mode":"html","author":"$undefined","summary":"$undefined"},{"id":391,"value":"You might want to work with binary data, such as a shapefile or a SQLite database. In these cases, the natural representation is typically an [ArrayBuffer](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer).","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined"},{"id":444,"value":"shapefile = require(\"shapefile@0.6\")","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined"},{"id":447,"value":"collection = shapefile.read(await FileAttachment(\"example.shp\").arrayBuffer())","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined"},{"id":114,"value":"You can also get a [ReadableStream](https://streams.spec.whatwg.org/#rs) if you want to read a file incrementally.","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined"},{"id":112,"value":"chunk = {\n const stream = await FileAttachment(\"example.shp\").stream();\n const reader = stream.getReader();\n let done, value;\n while (({done, value} = await reader.read()), !done) {\n yield value;\n }\n}","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined"},{"id":53,"value":"In rare cases (for example, passing a file reference to web worker), you might want a Blob or the URL directly. For example, here’s a link to download a PDF attached to this notebook.","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined"},{"id":464,"value":"Click here to download a PDF.","pinned":true,"hidden":false,"mode":"html","author":"$undefined","summary":"$undefined"},{"id":645,"value":"And here’s a Blob that you might pass to a web worker.","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined"},{"id":34,"value":"blob = FileAttachment(\"example.csv\").blob()","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined"},{"id":923,"value":"You can parse data from Microsoft Excel files. See [FileAttachment.xlsx()](https://observablehq.com/@observablehq/xlsx?collection=@observablehq/getting-data-in-and-out) for details.\n\nSimilarly, you can read data from `.zip` files. See [FileAttachment.zip()](https://observablehq.com/@observablehq/zip?collection=@observablehq/getting-data-in-and-out) for details.","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined"},{"id":350,"value":"Lastly, if you pass an unknown file name to FileAttachment, it throws an error. This is true even if you don’t load the file’s contents because Observable tracks the set of known files using static analysis.","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined"},{"id":481,"value":"FileAttachment(\"exemple.txt\") // Oops!","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined"},{"id":107,"value":"### How files work\n\nHere are a few more details about files you might want to know.","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined"},{"id":9,"value":"**Files are local to the notebook.** Files can’t be referenced across notebooks—a given file can be directly accessed only by its notebook. You can, however, import cells that use files across notebooks. Likewise, when you fork a notebook, you’ll get your own copy of any attached files.","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined"},{"id":7,"value":"**Files are immutable.** The contents associated with a given file name never change. Instead of replacing a file’s contents, you replace a file, which automatically generates a new name and updates all code references to point to the new file. This preserves [notebook history](/@observablehq/history): you can view any version of your notebook and see the original data, and compare different versions of files.","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined"},{"id":211,"value":"**But, files can be deleted.** While file immutability ensures that you can go back in time to see earlier versions of a notebook, we recognize that there are times when you simply want a file taken down for good. In this case, delete the file from the files pane. This will cause references to the deleted file to error (and break old versions of the notebook).","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined"},{"id":267,"value":"**File sizes are limited.** Files up to 50 megabytes can be uploaded. There’s also a rolling quota of 1GB per user over a 28-day period on uploads. For Teams, the quota is pooled for all editors on the team, so a team with 10 editors has a 10GB quota. There is no cap on the total file size usage per user. (For larger files, you’ll either need to host the files yourself, or use a [local file input](/@observablehq/input-file).)","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined"},{"id":12,"value":"**Files in private notebooks are private.** When you make a notebook public, only the files _currently used_ by the notebook will become public. A file you replaced or stopped using—as long as you no longer reference it—will remain private. See below.","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined"},{"id":190,"value":"**References to files are parsed statically.** We use static analysis to determine which files a notebook uses so that we can automatically publish referenced files when a notebook is published (and *only* referenced files), and similarly copy only referenced files when forking a notebook. The FileAttachment function thus accepts only literal strings; code such as\n\n~~~js\nFileAttachment(\"my\" + \"file.csv\")\n~~~\n\nor similar dynamic invocation is invalid syntax. For details on how this is implemented, see [our parser](https://github.com/observablehq/parser).","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined"},{"id":285,"value":"---\n\n## Appendix","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined"},{"id":289,"value":"keys = s => htl.html`${keysText(s)}`","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined"},{"id":288,"value":"import {keys as keysText, mac} from \"@observablehq/keys\"","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined"}],"files":"$W31","stdlib":"1","titling":"auto"}} 2e:"$2d:body"