New

The executive guide to generative AI

Read more
About usPartnersSupport|Login
« 关闭索引 API 创建或更新别名 API »
Elastic 文档 ›Elasticsearch 指南 [8.17] ›REST API ›索引 API

创建索引 API

编辑

创建索引 API

编辑

创建一个新的索引。

resp = client.indices.create(
    index="my-index-000001",
)
print(resp)
response = client.indices.create(
  index: 'my-index-000001'
)
puts response
const response = await client.indices.create({
  index: "my-index-000001",
});
console.log(response);
PUT /my-index-000001
Copy as curlTry in Elastic 

请求

编辑

PUT /<index>

先决条件

编辑
  • 如果启用了 Elasticsearch 安全功能，您必须拥有目标索引的 create_index 或 manage 索引权限。要将索引添加到别名，您必须拥有该别名的 manage 索引权限。

描述

编辑

您可以使用创建索引 API 将新索引添加到 Elasticsearch 集群。创建索引时，您可以指定以下内容：

  • 索引的设置
  • 索引中字段的映射
  • 索引别名

路径参数

编辑
<index>

（必需，字符串）您希望创建的索引的名称。

索引名称必须满足以下条件：

  • 仅限小写
  • 不能包含 \、/、*、?、"、<、>、|、` `（空格字符）、,、#
  • 7.0 之前的索引可以包含冒号 (:)，但这已被弃用，并且在 7.0+ 中将不再支持
  • 不能以 -、_、+ 开头
  • 不能为 . 或 ..
  • 长度不能超过 255 个字节（请注意，它是字节，因此多字节字符会更快地计入 255 的限制）
  • 以 . 开头的名称已被弃用，但 隐藏索引和插件管理的内部索引除外

查询参数

编辑
wait_for_active_shards

（可选，字符串）在继续操作之前必须处于活动状态的每个分片的副本数。设置为 all 或任何非负整数，最大值为索引中每个分片副本的总数 (number_of_replicas+1)。默认为 1，表示仅等待每个主分片处于活动状态。

请参阅 活动分片。

master_timeout
（可选，时间单位）等待主节点的时间。如果主节点在超时过期之前不可用，则请求失败并返回错误。默认为 30s。也可以设置为 -1，表示请求永远不应超时。
timeout
（可选，时间单位）在更新集群元数据后，等待集群中所有相关节点响应的时间。如果在超时过期之前未收到响应，则集群元数据更新仍然适用，但响应将指示它未被完全确认。默认为 30s。也可以设置为 -1，表示请求永远不应超时。

请求正文

编辑
aliases

（可选，对象数组）索引的别名。

aliases 对象的属性
<alias>

（必需，对象）键是别名名称。索引别名名称支持日期数学。

对象正文包含别名的选项。支持空对象。

<alias> 的属性
filter
（可选，查询 DSL 对象）用于限制别名可以访问的文档的查询。
index_routing
（可选，字符串）用于将索引操作路由到特定分片的值。如果指定，此值将覆盖索引操作的 routing 值。
is_hidden
（可选，布尔值）如果为 true，则别名是隐藏的。默认为 false。别名的所有索引必须具有相同的 is_hidden 值。
is_write_index
（可选，布尔值）如果为 true，则该索引是别名的写入索引。默认为 false。
routing
（可选，字符串）用于将索引和搜索操作路由到特定分片的值。
search_routing
（可选，字符串）用于将搜索操作路由到特定分片的值。如果指定，此值将覆盖搜索操作的 routing 值。
mappings

（可选，映射对象）索引中字段的映射。如果指定，此映射可以包括：

请参阅 映射。

settings
（可选，索引设置对象）索引的配置选项。请参阅 索引设置。

示例

编辑

索引设置

编辑

创建的每个索引都可以具有与其关联的特定设置，这些设置在正文中定义。

resp = client.indices.create(
    index="my-index-000001",
    settings={
        "index": {
            "number_of_shards": 3,
            "number_of_replicas": 2
        }
    },
)
print(resp)
response = client.indices.create(
  index: 'my-index-000001',
  body: {
    settings: {
      index: {
        number_of_shards: 3,
        number_of_replicas: 2
      }
    }
  }
)
puts response
const response = await client.indices.create({
  index: "my-index-000001",
  settings: {
    index: {
      number_of_shards: 3,
      number_of_replicas: 2,
    },
  },
});
console.log(response);
PUT /my-index-000001
{
  "settings": {
    "index": {
      "number_of_shards": 3,  
      "number_of_replicas": 2 
    }
  }
}
Copy as curlTry in Elastic 

number_of_shards 的默认值为 1

number_of_replicas 的默认值为 1（即每个主分片一个副本）

或更简化：

resp = client.indices.create(
    index="my-index-000001",
    settings={
        "number_of_shards": 3,
        "number_of_replicas": 2
    },
)
print(resp)
response = client.indices.create(
  index: 'my-index-000001',
  body: {
    settings: {
      number_of_shards: 3,
      number_of_replicas: 2
    }
  }
)
puts response
const response = await client.indices.create({
  index: "my-index-000001",
  settings: {
    number_of_shards: 3,
    number_of_replicas: 2,
  },
});
console.log(response);
PUT /my-index-000001
{
  "settings": {
    "number_of_shards": 3,
    "number_of_replicas": 2
  }
}
Copy as curlTry in Elastic 

您不必在 settings 部分内显式指定 index 部分。

有关创建索引时可以设置的所有不同索引级别设置的更多信息，请查看索引模块部分。

映射

编辑

创建索引 API 允许提供映射定义

resp = client.indices.create(
    index="test",
    settings={
        "number_of_shards": 1
    },
    mappings={
        "properties": {
            "field1": {
                "type": "text"
            }
        }
    },
)
print(resp)
response = client.indices.create(
  index: 'test',
  body: {
    settings: {
      number_of_shards: 1
    },
    mappings: {
      properties: {
        "field1": {
          type: 'text'
        }
      }
    }
  }
)
puts response
res, err := es.Indices.Create(
	"test",
	es.Indices.Create.WithBody(strings.NewReader(`{
	  "settings": {
	    "number_of_shards": 1
	  },
	  "mappings": {
	    "properties": {
	      "field1": {
	        "type": "text"
	      }
	    }
	  }
	}`)),
)
fmt.Println(res, err)
const response = await client.indices.create({
  index: "test",
  settings: {
    number_of_shards: 1,
  },
  mappings: {
    properties: {
      field1: {
        type: "text",
      },
    },
  },
});
console.log(response);
PUT /test
{
  "settings": {
    "number_of_shards": 1
  },
  "mappings": {
    "properties": {
      "field1": { "type": "text" }
    }
  }
}
Copy as curlTry in Elastic 

别名

编辑

创建索引 API 还允许提供一组 别名

resp = client.indices.create(
    index="test",
    aliases={
        "alias_1": {},
        "alias_2": {
            "filter": {
                "term": {
                    "user.id": "kimchy"
                }
            },
            "routing": "shard-1"
        }
    },
)
print(resp)
response = client.indices.create(
  index: 'test',
  body: {
    aliases: {
      "alias_1": {},
      "alias_2": {
        filter: {
          term: {
            'user.id' => 'kimchy'
          }
        },
        routing: 'shard-1'
      }
    }
  }
)
puts response
const response = await client.indices.create({
  index: "test",
  aliases: {
    alias_1: {},
    alias_2: {
      filter: {
        term: {
          "user.id": "kimchy",
        },
      },
      routing: "shard-1",
    },
  },
});
console.log(response);
PUT /test
{
  "aliases": {
    "alias_1": {},
    "alias_2": {
      "filter": {
        "term": { "user.id": "kimchy" }
      },
      "routing": "shard-1"
    }
  }
}
Copy as curlTry in Elastic 

索引别名名称还支持日期数学。

resp = client.indices.create(
    index="logs",
    aliases={
        "<logs_{now/M}>": {}
    },
)
print(resp)
response = client.indices.create(
  index: 'logs',
  body: {
    aliases: {
      "<logs_{now/M}>": {}
    }
  }
)
puts response
const response = await client.indices.create({
  index: "logs",
  aliases: {
    "<logs_{now/M}>": {},
  },
});
console.log(response);
PUT /logs
{
  "aliases": {
    "<logs_{now/M}>": {}
  }
}
Copy as curlTry in Elastic 

等待活动分片

编辑

默认情况下，只有当每个分片的主副本都已启动或请求超时时，索引创建才会向客户端返回响应。索引创建响应将指示发生了什么

{
  "acknowledged": true,
  "shards_acknowledged": true,
  "index": "logs"
}

acknowledged 指示索引是否在集群中成功创建，而 shards_acknowledged 指示在超时之前，索引中每个分片的必要分片副本数是否已启动。请注意，acknowledged 或 shards_acknowledged 仍可能为 false，但索引创建是成功的。这些值仅指示操作是否在超时之前完成。如果 acknowledged 为 false，那么我们在集群状态更新为新创建的索引之前超时了，但它可能很快就会创建。如果 shards_acknowledged 为 false，那么我们在必要数量的分片启动之前超时了（默认情况下仅为主分片），即使集群状态已成功更新以反映新创建的索引（即 acknowledged=true）。

我们可以通过索引设置 index.write.wait_for_active_shards 来更改仅等待主分片启动的默认设置（请注意，更改此设置也会影响所有后续写入操作上的 wait_for_active_shards 值）

resp = client.indices.create(
    index="test",
    settings={
        "index.write.wait_for_active_shards": "2"
    },
)
print(resp)
response = client.indices.create(
  index: 'test',
  body: {
    settings: {
      'index.write.wait_for_active_shards' => '2'
    }
  }
)
puts response
res, err := es.Indices.Create(
	"test",
	es.Indices.Create.WithBody(strings.NewReader(`{
	  "settings": {
	    "index.write.wait_for_active_shards": "2"
	  }
	}`)),
)
fmt.Println(res, err)
const response = await client.indices.create({
  index: "test",
  settings: {
    "index.write.wait_for_active_shards": "2",
  },
});
console.log(response);
PUT /test
{
  "settings": {
    "index.write.wait_for_active_shards": "2"
  }
}
Copy as curlTry in Elastic 

或通过请求参数 wait_for_active_shards

$params = [
    'index' => 'test',
];
$response = $client->indices()->create($params);
resp = client.indices.create(
    index="test",
    wait_for_active_shards="2",
)
print(resp)
response = client.indices.create(
  index: 'test',
  wait_for_active_shards: 2
)
puts response
res, err := es.Indices.Create("test?wait_for_active_shards=2")
fmt.Println(res, err)
const response = await client.indices.create({
  index: "test",
  wait_for_active_shards: 2,
});
console.log(response);
PUT /test?wait_for_active_shards=2
Copy as curlTry in Elastic 

有关 wait_for_active_shards 及其可能值的详细说明，请在此处查看 活动分片。

« 关闭索引 API 创建或更新别名 API »