31:T767,md`### Attaching files We offer several convenient ways to attach files. 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. Open the files pane by clicking File Attachments in the notebook menu . From there, drag-and-drop a file from your desktop to attach it. If a cell references files, a file icon appears in the top-right corner of the cell editor. Click this to inspect the files or to replace a file with a new local file.`32:[{"id":"1a485a6468d79a87fe0794e1119dee719716ec2b2f91d26e04e88bc3faa739c11fca8cd3d85d2e525c4ed936a6f7b9bc1b530c4fa00df82a82fc63525ca17d9e","href":"https://static.observableusercontent.com/files/1a485a6468d79a87fe0794e1119dee719716ec2b2f91d26e04e88bc3faa739c11fca8cd3d85d2e525c4ed936a6f7b9bc1b530c4fa00df82a82fc63525ca17d9e","name":"example.pdf","type":"application/pdf","lastModified":1572958271871.914,"size":27483},{"id":"1bc7c60612fed26b5376e8648f66b956192d6698e532730c148ea00491a6ff0122dc5cdf605f8d6ae209c4547176c2da042296b7665f4ace4eabda3d4500762c","href":"https://static.observableusercontent.com/files/1bc7c60612fed26b5376e8648f66b956192d6698e532730c148ea00491a6ff0122dc5cdf605f8d6ae209c4547176c2da042296b7665f4ace4eabda3d4500762c","name":"example.shp","type":"application/octet-stream","lastModified":1572958271871.914,"size":498480},{"id":"e2a5a0ac299b53fc1016e082c7c0732d50d0dc9388d8b99adadeee40d6d1c856991c15698dcdf582a6827b411ba6d470bf7a6d28426fb8bc1cd7cc28f17199bd","href":"https://static.observableusercontent.com/files/e2a5a0ac299b53fc1016e082c7c0732d50d0dc9388d8b99adadeee40d6d1c856991c15698dcdf582a6827b411ba6d470bf7a6d28426fb8bc1cd7cc28f17199bd","name":"the-persistence-of-memory.jpg","type":"image/jpeg","lastModified":1572958271871.914,"size":179013},{"id":"a86c4f95f3ec10fd2d13544ecf6bdf49ae25066ba2e8b2ca96fddd0a831c09cd2ac0ffb441e2e6db6258648fbe267b413d71937c17b4a0d80e1822d99ba2fb0a","href":"https://static.observableusercontent.com/files/a86c4f95f3ec10fd2d13544ecf6bdf49ae25066ba2e8b2ca96fddd0a831c09cd2ac0ffb441e2e6db6258648fbe267b413d71937c17b4a0d80e1822d99ba2fb0a","name":"example.png","type":"image/png","lastModified":1572958271871.914,"size":126867},{"id":"09f63bb9ff086fef80717e2ea8c974f918a996d2bfa3d8773d3ae12753942c002d0dfab833d7bee1e0c9cd358cd3578c1cd0f9435595e76901508adc3964bbdc","href":"https://static.observableusercontent.com/files/09f63bb9ff086fef80717e2ea8c974f918a996d2bfa3d8773d3ae12753942c002d0dfab833d7bee1e0c9cd358cd3578c1cd0f9435595e76901508adc3964bbdc","name":"example.csv","type":"application/octet-stream","lastModified":1572958271871.914,"size":275},{"id":"86ff47388d832e549c0661861f8107e4e65187de3333abf70f940359eac7810c611eebb7511565264f4b8b001229fd9a6832a21a421c6be3623ccbd97cbf5737","href":"https://static.observableusercontent.com/files/86ff47388d832e549c0661861f8107e4e65187de3333abf70f940359eac7810c611eebb7511565264f4b8b001229fd9a6832a21a421c6be3623ccbd97cbf5737","name":"example.json","type":"application/octet-stream","lastModified":1572958271871.914,"size":53},{"id":"64d21082dcd00f21843ac22313ce443c1faa36a462afdb3c063f7cadea1c5d22a959c4aa3e89db2d7ecf2533689e0cf63659dc4058774654aae62049ecbaa940","href":"https://static.observableusercontent.com/files/64d21082dcd00f21843ac22313ce443c1faa36a462afdb3c063f7cadea1c5d22a959c4aa3e89db2d7ecf2533689e0cf63659dc4058774654aae62049ecbaa940","name":"national-archive.jpg","type":"image/jpeg","lastModified":1572958271871.914,"size":409265}] 2f:{"title":"File Attachments","cells":[{"id":260,"value":"md`# 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":"ojs"},{"id":0,"value":"md`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!).\n\nFile 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":"ojs"},{"id":142,"value":"md`(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.)`","pinned":false,"hidden":false,"mode":"ojs"},{"id":22,"value":"$31","pinned":false,"hidden":false,"mode":"ojs"},{"id":82,"value":"using = md`### 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":"ojs"},{"id":27,"value":"attachment = FileAttachment(\"example.json\")","pinned":true,"hidden":false,"mode":"ojs"},{"id":658,"value":"md`*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":"ojs"},{"id":29,"value":"md`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, text, or ArrayBuffer. You choose the appropriate method based on how you want to consume the file.\n\nHere are a few examples. First, bog standard JSON.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":36,"value":"json = FileAttachment(\"example.json\").json()","pinned":true,"hidden":false,"mode":"ojs"},{"id":410,"value":"json.hello.world","pinned":true,"hidden":false,"mode":"ojs"},{"id":382,"value":"md`How about comma-separated values (CSV)? There’s no built-in method for it, but it’s text-based, so we can start by loading the text.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":31,"value":"text = FileAttachment(\"example.csv\").text()","pinned":true,"hidden":false,"mode":"ojs"},{"id":370,"value":"md`Calling *attachment*.text returns a promise to a string, so we must wait for this promise to resolve before calling [d3.csvParse](https://github.com/d3/d3-dsv/blob/master/README.md#csvParse). (We’ll also use [d3.autoType](/@d3/d3-autotype) for useful types. You can use a different library than [d3-dsv](https://github.com/d3/d3-dsv) if you prefer!)`","pinned":false,"hidden":false,"mode":"ojs"},{"id":399,"value":"d3 = require(\"d3-dsv@1\")","pinned":true,"hidden":false,"mode":"ojs"},{"id":417,"value":"md`We can reference the text loaded above with no await because Observable conveniently [awaits promises](/@observablehq/introduction-to-promises) across cell boundaries.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":415,"value":"d3.csvParse(text, d3.autoType)","pinned":true,"hidden":false,"mode":"ojs"},{"id":422,"value":"md`Alternatively, we can load and parse in a single cell using await.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":390,"value":"csv = d3.csvParse(await FileAttachment(\"example.csv\").text(), d3.autoType)","pinned":true,"hidden":false,"mode":"ojs"},{"id":57,"value":"md`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":"ojs"},{"id":42,"value":"image = FileAttachment(\"example.png\").image()","pinned":true,"hidden":false,"mode":"ojs"},{"id":554,"value":"md`To embed the image in Markdown or HTML literals, await it.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":558,"value":"html`

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

Image: Salvador Dali

\n`","pinned":true,"hidden":false,"mode":"ojs"},{"id":391,"value":"md`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":"ojs"},{"id":444,"value":"shapefile = require(\"shapefile@0.6\")","pinned":true,"hidden":false,"mode":"ojs"},{"id":447,"value":"collection = shapefile.read(await FileAttachment(\"example.shp\").arrayBuffer())","pinned":true,"hidden":false,"mode":"ojs"},{"id":114,"value":"md`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":"ojs"},{"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"},{"id":53,"value":"md`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":"ojs"},{"id":464,"value":"html`Click here to download a PDF.`","pinned":true,"hidden":false,"mode":"ojs"},{"id":645,"value":"md`And here’s a Blob that you might pass to a web worker.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":34,"value":"blob = FileAttachment(\"example.csv\").blob()","pinned":true,"hidden":false,"mode":"ojs"},{"id":350,"value":"md`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":"ojs"},{"id":481,"value":"FileAttachment(\"exemple.txt\") // Oops!","pinned":true,"hidden":false,"mode":"ojs"},{"id":107,"value":"md`### How files work\n\nHere are a few more details about files you might want to know.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":9,"value":"md`**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":"ojs"},{"id":7,"value":"md`**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":"ojs"},{"id":211,"value":"md`**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":"ojs"},{"id":267,"value":"md`**File sizes are limited.** Any type of file can be uploaded, but there’s currently a size limit of 15 megabytes per file. We might increase this in the future, and we’re considering higher limits for teams; let us know if you need to work with bigger files. There’s also a rolling quota per user on uploads.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":12,"value":"md`**Files are private by default,** just like notebooks. When you publish (or share) a notebook, 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":"ojs"},{"id":190,"value":"md`**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":"ojs"},{"id":285,"value":"md`---\n\n## Appendix`","pinned":false,"hidden":false,"mode":"ojs"},{"id":289,"value":"keys = s => html`${keysText(s)}`","pinned":false,"hidden":false,"mode":"ojs"},{"id":288,"value":"import {keys as keysText, mac} from \"@mbostock/keys\"","pinned":false,"hidden":false,"mode":"ojs"}],"files":"$W32","stdlib":"1","titling":"auto"}