1.6. 入门¶

在本文中，我们将快速浏览CouchDB的特性。我们将创建第一个文档并使用CouchDB视图进行实验。

1.6.1. 所有系统都启动了！¶

我们将使用命令行实用程序curl快速了解CouchDB的基本应用程序编程接口（API）。请注意，这不是与CouchDB对话的唯一方式。我们将在其余文件中向您展示更多内容。curl的有趣之处在于它使您能够控制原始的HTTP请求，并且您可以确切地看到数据库的“引擎盖”下到底发生了什么。

确保CouchDB仍在运行，然后执行以下操作：

curl http://127.0.0.1:5984/

这将向新安装的CouchDB实例发出GET请求。

回复应该是这样的：

{
  "couchdb": "Welcome",
  "version": "3.0.0",
  "git_sha": "83bdcf693",
  "uuid": "56f16e7c93ff4a2dc20eb6acc7000b71",
  "features": [
    "access-ready",
    "partitioned",
    "pluggable-storage-engines",
    "reshard",
    "scheduler"
  ],
  "vendor": {
    "name": "The Apache Software Foundation"
  }
}

不是那么壮观。CouchDB正在用运行的版本号打招呼。

接下来，我们可以得到一个数据库列表：

curl -X GET http://admin:password@127.0.0.1:5984/_all_dbs

我们在前一个请求中添加的全部内容是ualldbs字符串，以及我们的管理员用户名和密码（在安装CouchDB时设置）。

回答应该是这样的：

["_replicator","_users"]

注解

如果这为您返回一个空数组，则表示您没有正确完成安装。请参考安装程序关于这方面的更多信息。

在本例中，我们将不显示超过此点的系统数据库。在 your 安装，随时 GET /_all_dbs ，您也应该在列表中看到系统数据库。

哦，没错，我们还没有创建任何用户数据库！

注解

curl命令默认发出GET请求。您可以使用 curl -X POST . 为了便于处理终端历史，我们通常使用 -X 即使在发出GET请求时也是如此。如果我们下次想发帖子，我们只需要改变方法。

HTTP在幕后的作用比在这里的示例中看到的要多一些。如果你对导线上的每一个细节都感兴趣，请将 -v 选项（例如。， curl -vX GET )，它将向您显示curl尝试连接的服务器、它发送的请求头和它接收回的响应头。非常适合调试！

让我们创建一个数据库：

curl -X PUT http://admin:password@127.0.0.1:5984/baseball

CouchDB将答复：

{"ok":true}

再次检索数据库列表显示了一些有用的结果：

curl -X GET http://admin:password@127.0.0.1:5984/_all_dbs

["baseball"]

注解

这里我们应该提到JavaScript对象表示法（JSON），CouchDB说明了数据格式。JSON是一种基于JavaScript语法的轻量级数据交换格式。因为JSON与JavaScript本机兼容，所以web浏览器是CouchDB的理想客户机。

括号 ([] )表示有序列表和大括号 ({{}} )表示键/值字典。键必须是字符串，用引号分隔 (" )，值可以是字符串、数字、布尔值、列表或键/值字典。有关JSON的更详细描述，请参阅附录E，JSON Primer。

让我们创建另一个数据库：

curl -X PUT http://admin:password@127.0.0.1:5984/baseball

CouchDB将答复：

{"error":"file_exists","reason":"The database could not be created,
the file already exists."}

我们已经有了一个具有该名称的数据库，因此CouchDB将响应一个错误。让我们用另一个数据库名称再试一次：

curl -X PUT http://admin:password@127.0.0.1:5984/plankton

CouchDB将答复：

{"ok":true}

再次检索数据库列表会显示一些有用的结果：

curl -X GET http://admin:password@127.0.0.1:5984/_all_dbs

CouchDB将以以下方式响应：

["baseball", "plankton"]

为了完成任务，我们删除第二个数据库：

curl -X DELETE http://admin:password@127.0.0.1:5984/plankton

CouchDB将答复：

{"ok":true}

数据库列表现在与以前相同：

curl -X GET http://admin:password@127.0.0.1:5984/_all_dbs

CouchDB将以以下方式响应：

["baseball"]

为了简洁起见，我们将跳过对文档的处理，因为下一节将介绍一种使用CouchDB的不同且可能更简单的方法，该方法应该提供相关的经验。在我们学习这个例子的时候，请记住“在幕后”所有的事情都是由应用程序完成的，就像您在这里手动完成的一样。所有操作都是使用带有URI的GET、PUT、POST和DELETE完成的。

1.6.2. 欢迎来到福克斯顿¶

在看过CouchDB的原始API之后，让我们来体验一下Fauxton，一个内置的管理接口。Fauxton提供了对CouchDB的所有特性的完全访问，并使得处理涉及到的一些更复杂的思想变得更加容易。使用Fauxton，我们可以创建和销毁数据库；查看和编辑文档；编写和运行MapReduce视图；触发数据库之间的复制。

要在浏览器中加载Faxton，请访问：

http://127.0.0.1:5984/_utils/

并在提示输入管理员密码时登录。

在后面的文档中，我们将重点讨论如何从服务器端语言（如Ruby和Python）中使用CouchDB。因此，本文档是一个很好的机会来展示一个使用CouchDB的集成web服务器（您可能希望用自己的应用程序来做的事情）来本机提供动态web应用程序的示例。

对于CouchDB的新安装，我们应该做的第一件事是运行测试套件，以验证一切都正常工作。这保证了我们可能遇到的任何问题都不是由于我们的设置中的麻烦问题造成的。同样，Fauxton测试套件中的失败是一个危险信号，它告诉我们在尝试使用一个可能损坏的数据库服务器之前要仔细检查我们的安装，这样当没有任何东西像我们预期的那样工作时，就避免了我们的困惑！

要验证您的安装，请单击 Verify 绿色的手，然后按左边的链环 Verify Installation 按钮。所有的测试都应该通过复选标记。如果有任何失败，请重新检查安装步骤。

1.6.3. 您的第一个数据库和文档¶

在Fauxton中创建数据库很简单。在“概述”页面中，单击“创建数据库”。当要求输入名称时，输入 hello-world 然后单击“创建”按钮。

创建数据库后，Fauxton将显示其所有文档的列表。这个列表将以空开始，所以让我们创建第一个文档。单击“所有文档”旁边的加号并选择“新建文档”链接。CouchDB将为您生成一个UUID。

出于演示的目的，让CouchDB分配一个UUID就可以了。当您编写第一个程序时，我们建议您分配自己的uuid。如果您依赖服务器生成UUID，并且由于第一个POST请求失败而导致发出两个POST请求，那么您可能会生成两个文档，而永远无法找到第一个文档，因为只有第二个文档会被报告回来。生成自己的uuid可以确保您永远不会得到重复的文档。

Fauxton将显示新创建的文档，以及它的u id字段。要创建新字段，只需使用编辑器编写有效的JSON。通过在 _id 值，然后添加文本：

"hello": "my new value"

单击绿色的“创建文档”按钮完成文档的创建。

您可以尝试使用其他JSON值；例如。， [1, 2, "c"] 或 {{"foo": "bar"}} .

您会注意到，该文档的版本已经添加。我们将在后面的文档中对此进行更详细的介绍，但现在，需要注意的一点是，在保存文档时，u rev就像一个安全功能。只要您和CouchDB就文档的最新版本达成一致，就可以成功地保存更改。

为清晰起见，您可能希望在“所有文档”视图中显示文档的内容。要启用此功能，请从窗口的右上角选择“选项”，然后选中“包括文档”选项。最后，按runquery按钮。完整文档应与 _id 和 _rev 价值观。

1.6.4. 运行芒果查询¶

既然我们已经成功地存储了文档，我们希望能够查询它们。在CouchDB中最简单的方法是运行Mango查询。Mango查询总是有两个部分：索引和选择器。

索引指定要查询的字段，选择器包含实际的查询参数，这些参数定义了我们要查找的内容。

索引存储为按指定字段排序的行。这使得从一系列键中检索数据变得高效，即使在有数千或数百万行时也是如此。

在运行示例查询之前，我们需要一些数据来运行它。我们将创建包含电影信息的文档。让我们为三部电影创建文档。（允许CouchDB生成 _id 和 _rev 字段。）使用Fauxton创建最终JSON结构的文档，如下所示：

{
    "_id": "00a271787f89c0ef2e10e88a0c0001f4",
    "type": "movie",
    "title": "My Neighbour Totoro",
    "year": 1988,
    "director": "miyazaki",
    "rating": 8.2
}

{
    "_id": "00a271787f89c0ef2e10e88a0c0003f0",
    "type": "movie",
    "title": "Kikis Delivery Service",
    "year": 1989,
    "director": "miyazaki",
    "rating": 7.8
}

{
    "_id": "00a271787f89c0ef2e10e88a0c00048b",
    "type": "movie",
    "title": "Princess Mononoke",
    "year": 1997,
    "director": "miyazaki",
    "rating": 8.4
}

现在我们想在电影发行年份找到一部电影，我们需要创建一个芒果索引。为此，请转到数据库概述中的“使用芒果运行查询”。然后单击“管理索引”，将左侧的索引字段改为如下所示：

{
   "index": {
      "fields": [
         "year"
      ]
   },
   "name": "year-json-index",
   "type": "json"
}

这将定义字段上的索引 year 并允许我们发送特定年份的文档查询。

接下来，单击“编辑查询”并将芒果查询更改为如下所示：

{
   "selector": {
      "year": {
         "$eq": 1988
      }
   }
}

然后单击“运行查询”。

结果应该是一个单一的结果，电影“我的邻居Totoro”的年价值是1988年。 $eq 这里代表“平等”。

注解

请注意，如果跳过添加索引，则查询仍将返回正确的结果，尽管您将看到有关不使用预先存在的索引的警告。在小型数据库中不使用索引可以很好地工作，并且在开发或培训中测试查询也是可以接受的，但是我们强烈反对在任何其他情况下使用索引，因为索引对于良好的查询性能是绝对重要的。

您还可以使用此选择器查询1980年代的所有电影：

{
   "selector": {
      "year": {
         "$lt": 1990,
         "$gte": 1980
      }
   }
}

结果是1988年和1989年的两部电影。 $lt 这里的意思是“低于”，并且 $gte 意思是“大于或等于”。后者目前没有任何效果，因为我们所有的电影都比1980年更新，但这使得查询经得起未来检验，并允许我们以后添加旧电影。

1.6.5. 触发复制¶

Fauxton可以触发两个本地数据库之间，本地和远程数据库之间，甚至两个远程数据库之间的复制。我们将向您展示如何将数据从一个本地数据库复制到另一个本地数据库，这是在我们学习示例时备份数据库的一种简单方法。

首先，我们需要创建一个空数据库作为复制的目标。返回数据库概述并创建一个名为 hello-replication . 现在单击侧栏中的“复制”并选择 hello-world 作为来源和 hello-replication 作为目标。单击“复制”复制数据库。

要查看复制的结果，请再次单击“数据库”选项卡。你应该看看 hello-replication 数据库的文档数与 hello-world 数据库，它应该占用大致相同的大小。

注解

对于较大的数据库，复制可能需要更长的时间。在进行复制时保持浏览器窗口打开是很重要的。另一种选择是，您可以通过curl或其他可以处理长时间运行连接的HTTP客户端来触发复制。如果客户端在复制完成之前关闭了连接，则必须重新触发它。幸运的是，CouchDB的复制可以从它停止的地方接管，而不是从头开始。

1.6.6. 总结¶

现在您已经了解了faugston的大部分特性，接下来的几个文档中我们将构建示例应用程序，您将准备深入研究并检查您的数据。Fauxton管理CouchDB的纯JavaScript方法展示了如何使用CouchDB的httpapi和集成的web服务器来构建一个功能齐全的web应用程序。

但是，在我们到达之前，我们将再次查看CouchDB的httpapi——现在使用放大镜。我们蜷缩在沙发上放松一下。