本文为您介绍上报事件属性、事件公共属性时，数据落库存储至DataFinder的逻辑说明。

您首先需要了解事件属性的上报和落库存储的过程中，有三个基本流程：元数据注册、数据上报、数据落库存储。

1. 元数据注册：
   这个过程指的是事件属性/事件公共属性在DataFinder的元数据库中进行登记注册。
2. 数据上报：
   这个过程指的是通过客户端、服务端SDK等方式，将待采集的数据进行代码集成，当后续应用被最终用户使用时，一旦触发对应的埋点，即会将对应的数据按照各端的数据上报策略向DataFinder进行上报。
3. 数据落库存储：
   这个过程指的是数据上报至DataFinder，最终会存储在DataFinder的数据库中。

各个流程的详细逻辑说明请参见下文。

元数据注册

通用逻辑

• 这个过程指的是事件属性/事件公共属性在DataFinder的元数据库中进行登记注册。
  建议您先结合业务分析需求规划好埋点需求，如果有自定义事件和属性的分析需求，可先将对应事件和属性在DataFinder的元数据中进行登记注册。

• 通常有以下几种方式会实现元数据的注册：

  手动注册（推荐）	自动注册
  您可以在使用客户端或服务端SDK等方式上报数据之前，先根据埋点规划，在DataFinder的控制台 元数据管理>事件属性 页面中手动 创建事件属性/事件公共属性。创建完成后，即在DataFinder元数据中完成对应属性的登记注册。 手动注册的操作详情请参见事件属性。	如果您没有在DataFinder元数据页面中手动注册过某个属性数据，后续直接将数据往DataFinder上报时，DataFinder会先在元数据库中查看是否有注册过对应元数据，如果此前没有注册过，则接收到这条上报数据的同时，DataFinder会自动先为您将此元数据进行自动登记注册。
  注意事项： 属性注册时，不能存在同名属性。 自动注册时，如果存在同名的属性则自动注册失败。

  注意

  元数据注册后，后续实际进行数据接入上报时的数据一定要与注册时的结果一致，如果业务分析过程中需要调整，也建议同步修改元数据的注册结果和接入上报的SDK代码配置，始终保持两边的配置一致，否则可能会导致数据上报异常。

开启埋点强制验收

• 手动注册：由于手动注册的元数据已经在DataFinder元数据中完成登记注册，因此开了强制验收开关对手动注册的元数据无影响，后续有数据上报时，需埋点验收通过后属性属性才会存储到数据库，对已注册的元数据没有影响。
• 自动注册：如果开了强制验收开关，您需要手动验收通过之后，自动注册的元数据才能生效，生效后上报的数据才能继续落库存储；如果验收不通过，则无法完成元数据的自动注册。

数据上报

• 这个过程指的是通过客户端、服务端SDK等方式，将待采集的数据进行代码集成，当后续应用被最终用户使用时，一旦触发对应的埋点，即会将对应的数据按照各端的数据上报策略向DataFinder进行上报。

• 对于事件属性和事件公共属性，通常在上报数据中有固定的位置。

  属性数据上报示例	上报位置说明
  	事件属性：通常在上报数据的params中上报。 事件公共属性：通常在上报数据的header_custom中上报。 具体各端不同类型的属性数据的上报位置可参见对应端的数据接入文档。

落库存储

这个过程指的是数据上报至DataFinder，最终会存储在DataFinder的数据库中。

SaaS-云原生/SaaS-非云原生

在SaaS云原生和SaaS-非云原生环境中，落库存储可细化为以下流程：

1. 元数据校验：DataFinder会先判断属性类型（是事件属性还是事件公共属性），并根据判断结果在元数据中查找和校验对应类型的属性元数据。
   1. 属性类型判断：判断主要依据是上报数据所在的代码位置：
      • 在上报数据的params中上报的数据会被判定为事件属性。
      • 在上报数据的header_custom中上报的数据会被判定为事件公共属性。
   2. 元数据查询/注册：如果此属性此前从未注册过，DataFinder根据您上报的属性数据格式推导您当前属性的数据类型，根据推导后的数据类型自动为您完成元数据的登记注册，自动注册后进行落库存储。

      注意

      如果存在同名的属性，会自动注册失败。

   3. 事件关联关系校验/推导：
      • 对于判定为事件属性的数据：DataFinder会同时将上报的事件属性与事件进行关联，即将上报数据的params中的属性和事件进行关联，如果关联关系此前在元数据中从未注册过，也会自动为您登记注册属性和事件的关联关系。
      • 对于判定为事件公共属性的数据：默认事件公共属性和所有事件关联。
   4. 数据类型校验/推导：已完成注册的属性数据，会检验您上报的属性数据类型和注册的数据类型是否一致，如果不一致，会按照元数据注册时设置的数据类型进行强制转换，转化后进行落库存储。如果转化失败，那此条数据就会被丢弃，无法落库存储。
2. 落库存储：在元数据校验后，DataFinder会将上报的数据存储在数据库中。

   注意

   事件属性和事件公共属性在DataFinder的数据库中的存储位置和存储方式完全一致，不能存在同名属性。

私有化

在私有化环境中，落库存储可细化为以下流程：

1. 元数据校验：私有化场景下，DataFinder不关注上报数据的属性类型（是事件属性还是事件公共属性），会直接在元数据中查找和校验数据类型。
   1. 元数据查询/注册：
      • 如果上报的属性此前从未注册过，DataFinder根据您上报的属性数据在代码中的位置、数据格式推导您当前属性的属性类型、数据类型，根据推导后的结果自动为您完成元数据的登记注册，自动注册后进行落库存储。
        • 在上报数据的params中上报的数据会被判定为事件属性。
        • 在上报数据的header_custom中上报的数据会被判定为事件公共属性。
      • 已完成注册的属性数据，会检验您上报的属性数据类型和注册的数据类型是否一致，如果不一致，会按照元数据注册时设置的数据类型进行强制转换，转化后进行落库存储。转化失败会丢弃。

        注意

        在私有化环境中，如果属性此前在元数据中已经完成登记注册，则在属性校验时仅会校验属性数据类型的一致性，不会再根据属性数据上报的位置来校验属性类型的一致性。
        例如，某属性A在元数据中登记注册时注册为了事件属性，但是实际在数据上报时，在上报数据代码的header_custom中进行上报，最终DataFinder会将此条上报的数据正常落库存储，并在元数据中此属性的属性类型就是事件属性。

   2. 事件关联关系校验/推导：
      • 对于判定为事件属性的数据：DataFinder会同时将上报的事件属性与事件进行关联，即将上报数据的params中的属性和事件进行关联，如果关联关系此前在元数据中从未注册过，也会自动为您登记注册属性和事件的关联关系。
      • 对于判定为事件公共属性的数据：默认事件公共属性和所有事件关联。
2. 落库存储：在元数据校验后，DataFinder会将上报的数据存储在数据库中。

   注意

   事件属性和事件公共属性在DataFinder的数据库中的存储位置和存储方式完全一致，不能存在同名属性。

开启埋点强制验收

如果您在 元数据管理>事件属性 中修改了事件属性的类型，将事件属性修改为事件公共属性，或将事件公共属性修改为事件属性，修改前后数据的上报存储逻辑依旧遵循上述逻辑，以下以几个典型修改的场景为您示例属性类型修改后的影响。

示例1：原属性A为事件属性且已在元数据中登记注册过，有数据上报过，后续接入SDK代码变更将属性作为事件公共属性进行上报

• 示例场景：

  • 本示例场景中，用户未在DataFinder的元数据管理页面去修改属性类型，而是直接在接入SDK代码中修改属性上报的代码位置。
  • 原事件属性A已上报过（上报数据在params），修改为公共事件属性后，在公共事件属性中上报（上报数据在header_custom）。

• 变更前后逻辑说明：

  对比项	SaaS-云原生/SaaS-非云原生	私有化
  修改后数据上报逻辑	DataFinder会在元数据的属性中查询此前是否有名称为“A”的属性注册过——由于此前A是作为事件属性登记在元数据中，不能注册同名的属性，因此会自动注册失败，修改SDK代码后的上报数据无法正常落库存储。	修改为公共事件属性并上报后，DataFinder会在修改后数据上报时在元数据中查询，是否有同名的属性注册过——由于此前A是作为事件属性登记在元数据中，已经注册过，因此DataFinder会将此条上报数据就作为事件属性进行登记。 同时DataFinder会结合上报属性的数据类型与此前注册的事件属性元数据的数据类型进行一致性校验，如果不一致，会将上报的数据类型强制转化为元数据中登记的数据类型进行存储。 完成上述校验后，DataFinder将属性数据落库存储到数据库中。
  后续数据查询	完成数据落库存储后，后续在使用分析工具查询属性数据时： 查询时间在属性修改之后：无法查询到数据。 查询时间在属性修改之前：可查询到对应的属性数据，且属性类型为事件属性。	完成数据落库存储后，后续在使用分析工具查询属性数据时： 可查询到对应的属性数据。 属性类型为事件属性，不会因为上报在header_custom就变为事件公共属性。

示例2：原属性A为事件属性且已在元数据中登记注册过，在元数据管理页面修改属性类型为事件公共属性，在接入SDK代码中被作为事件公共属性上报

• 示例场景

  • 原事件属性A已在控制台的 元数据管理>事件属性 页面中登记注册过，后续将属性修改为事件公共属性，并将上报时接入SDK代码修改为事件公共属性上报（header_custom）。

• 变更前后逻辑说明：

  对比项	SaaS-云原生/SaaS-非云原生	私有化
  修改后数据上报逻辑	修改为公共事件属性并上报后，DataFinder会根据数据上报的位置header_custom判断当前上报的数据为事件公共属性。 判断为事件公共属性后，DataFinder会在元数据的事件公共属性中查询此前是否有名称为“A”的事件公共属性——由于属性A已修改为事件公共属性，已登记在元数据中，因此： DataFinder会将此条属性数据作为事件公共属性进行入库。 DataFinder会校验上报数据数据类型与元数据中的数据类型： 不一致的话会将数据类型转化为元数据中的数据类型。 转化失败则此条数据将会被丢弃不会落库存储。 完成上述元数据的校验后，DataFinder将属性数据落库存储到数据库中。	修改为公共事件属性并上报后，DataFinder会在修改后数据上报时在元数据中查询，是否有同名的属性注册过——由于属性A在元数据中已修改为事件公共属性，因此DataFinder会将此条上报数据就作为事件公共属性进行入库。 同时DataFinder会结合上报属性的数据类型与此前注册的事件属性元数据的数据类型进行一致性校验： 不一致的话会将数据类型转化为元数据中的数据类型。 转化失败则此条数据将会被丢弃不会落库存储。 完成上述校验后，DataFinder将属性数据落库存储到数据库中。